p53209761
/
test_ok2
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
test_ok2/changelog/README.rst

35 lines
1.8 KiB
ReStructuredText
Raw Normal View History

Small update to changelog/README.rst
2018-02-17 20:20:41 +08:00
This directory contains "newsfragments" which are short files that contain a small **ReST**-formatted
Add changelog/README.rst and streamline our PR template text This streamlines the PR template text and adds a more in-depth explanation about how the changelog entries work because this topic is a common source of confusion: - How to name the files. - Which formatting to use (people in general assume it is Markdown). - Recommend adding `.rst` extension to changelog files to help with the above (`towncrier` doesn't care). This was heavily inspired by the excellent python-trio/trio docs.
2018-02-07 08:13:04 +08:00
text that will be added to the next ``CHANGELOG``.
The ``CHANGELOG`` will be read by users, so this description should be aimed to pytest users
instead of describing internal changes which are only relevant to the developers.
apply most other hooks and opt out of black reformating
2018-05-18 16:19:46 +08:00
Make sure to use full sentences with correct case and punctuation, for example::
Small update to changelog/README.rst
2018-02-17 20:20:41 +08:00
Fix issue with non-ascii messages from the ``warnings`` module.
Add changelog/README.rst and streamline our PR template text This streamlines the PR template text and adds a more in-depth explanation about how the changelog entries work because this topic is a common source of confusion: - How to name the files. - Which formatting to use (people in general assume it is Markdown). - Recommend adding `.rst` extension to changelog files to help with the above (`towncrier` doesn't care). This was heavily inspired by the excellent python-trio/trio docs.
2018-02-07 08:13:04 +08:00
Each file should be named like ``<ISSUE>.<TYPE>.rst``, where
``<ISSUE>`` is an issue number, and ``<TYPE>`` is one of:
* ``feature``: new user facing features, like new command-line options and new behavior.
Add new 'improvement' changelog category This creates a separate section from 'features' for small changes which don't usually require user intervention, such as: * Human readable session duration * New junitxml fields * Improved colors in terminal * etc. The idea is to better match user expectations about new actual features in the "Features" section of the changelog.
2019-08-10 20:26:37 +08:00
* ``improvement``: improvement of existing functionality, usually without requiring user intervention (for example, new fields being written in ``--junitxml``, improved colors in terminal, etc).
Add changelog/README.rst and streamline our PR template text This streamlines the PR template text and adds a more in-depth explanation about how the changelog entries work because this topic is a common source of confusion: - How to name the files. - Which formatting to use (people in general assume it is Markdown). - Recommend adding `.rst` extension to changelog files to help with the above (`towncrier` doesn't care). This was heavily inspired by the excellent python-trio/trio docs.
2018-02-07 08:13:04 +08:00
* ``bugfix``: fixes a reported bug.
* ``doc``: documentation improvement, like rewording an entire session or adding missing docs.
Separate deprecations and removals in the CHANGELOG
2018-09-14 01:02:01 +08:00
* ``deprecation``: feature deprecation.
* ``removal``: feature removal.
Code review suggestions
2018-02-08 18:03:14 +08:00
* ``vendor``: changes in packages vendored in pytest.
Add changelog/README.rst and streamline our PR template text This streamlines the PR template text and adds a more in-depth explanation about how the changelog entries work because this topic is a common source of confusion: - How to name the files. - Which formatting to use (people in general assume it is Markdown). - Recommend adding `.rst` extension to changelog files to help with the above (`towncrier` doesn't care). This was heavily inspired by the excellent python-trio/trio docs.
2018-02-07 08:13:04 +08:00
* ``trivial``: fixing a small typo or internal change that might be noteworthy.
So for example: ``123.feature.rst``, ``456.bugfix.rst``.
If your PR fixes an issue, use that number here. If there is no issue,
then after you submit the PR and get the PR number you can add a
changelog using that instead.
If you are not sure what issue type to use, don't hesitate to ask in your PR.
Update README for CHANGELOG about using multiple paragraphs
2018-07-07 22:07:13 +08:00
``towncrier`` preserves multiple paragraphs and formatting (code blocks, lists, and so on), but for entries
other than ``features`` it is usually better to stick to a single paragraph to keep it concise. You can install
``towncrier`` and then run ``towncrier --draft``
Add changelog/README.rst and streamline our PR template text This streamlines the PR template text and adds a more in-depth explanation about how the changelog entries work because this topic is a common source of confusion: - How to name the files. - Which formatting to use (people in general assume it is Markdown). - Recommend adding `.rst` extension to changelog files to help with the above (`towncrier` doesn't care). This was heavily inspired by the excellent python-trio/trio docs.
2018-02-07 08:13:04 +08:00
if you want to get a preview of how your change will look in the final release notes.