README.rst (2064B)
1 This directory contains "newsfragments" which are short files that contain a small **ReST**-formatted 2 text that will be added to the next ``CHANGELOG``. 3 4 The ``CHANGELOG`` will be read by **users**, so this description should be aimed to pytest users 5 instead of describing internal changes which are only relevant to the developers. 6 7 Make sure to use full sentences in the **past or present tense** and use punctuation, examples:: 8 9 Improved verbose diff output with sequences. 10 11 Terminal summary statistics now use multiple colors. 12 13 Each file should be named like ``<ISSUE>.<TYPE>.rst``, where 14 ``<ISSUE>`` is an issue number, and ``<TYPE>`` is one of: 15 16 * ``feature``: new user facing features, like new command-line options and new behavior. 17 * ``improvement``: improvement of existing functionality, usually without requiring user intervention (for example, new fields being written in ``--junit-xml``, improved colors in terminal, etc). 18 * ``bugfix``: fixes a bug. 19 * ``doc``: documentation improvement, like rewording an entire session or adding missing docs. 20 * ``deprecation``: feature deprecation. 21 * ``breaking``: a change which may break existing suites, such as feature removal or behavior change. 22 * ``vendor``: changes in packages vendored in pytest. 23 * ``trivial``: fixing a small typo or internal change that might be noteworthy. 24 25 So for example: ``123.feature.rst``, ``456.bugfix.rst``. 26 27 If your PR fixes an issue, use that number here. If there is no issue, 28 then after you submit the PR and get the PR number you can add a 29 changelog using that instead. 30 31 If you are not sure what issue type to use, don't hesitate to ask in your PR. 32 33 ``towncrier`` preserves multiple paragraphs and formatting (code blocks, lists, and so on), but for entries 34 other than ``features`` it is usually better to stick to a single paragraph to keep it concise. 35 36 You can also run ``tox -e docs`` to build the documentation 37 with the draft changelog (``doc/en/_build/html/changelog.html``) if you want to get a preview of how your change will look in the final release notes.