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

38 lines
2.0 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``.
Improve instructions on how to write CHANGELOG entries This makes easier for contributors to get the CHANGELOG entry right the first time.
2019-11-20 01:04:21 +08:00
The ``CHANGELOG`` will be read by **users**, so this description should be aimed to pytest users
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
instead of describing internal changes which are only relevant to the developers.
Improve instructions on how to write CHANGELOG entries This makes easier for contributors to get the CHANGELOG entry right the first time.
2019-11-20 01:04:21 +08:00
Make sure to use full sentences in the **past or present tense** and use punctuation, examples::
Small update to changelog/README.rst
2018-02-17 20:20:41 +08:00
Improve instructions on how to write CHANGELOG entries This makes easier for contributors to get the CHANGELOG entry right the first time.
2019-11-20 01:04:21 +08:00
Improved verbose diff output with sequences.
Terminal summary statistics now use multiple colors.
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).
bug-fix fixes
2020-01-24 03:34:21 +08:00
* ``bugfix``: fixes a bug.
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
* ``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.
Replace 'removal' by 'breaking' changelog category As discussed, sometimes we will need to introduce changes which are not necessarily removals but might break existing suites
2019-12-06 19:47:39 +08:00
* ``breaking``: a change which may break existing suites, such as feature removal or behavior change.
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
docs: move changelog to docs/en and allow sphinx directives Now `tox -e docs` will also include the draft changelog for the next version (locally only). `CHANGELOG.rst` now only points to the changelog on READTHEDOCS so sphinx diretives can be used. Followup to https://github.com/pytest-dev/pytest/pull/6272
2019-11-25 11:06:30 +08:00
other than ``features`` it is usually better to stick to a single paragraph to keep it concise.
You can also run ``tox -e docs`` to build the documentation
docs: use doc/en/_build/html for html output (#6842) This will use the same directory as `make -C doc/en` then, and reflects the default location that Sphinx uses.
2020-02-29 07:47:30 +08:00
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.