diff options
author | Jason R. Coombs <jaraco@jaraco.com> | 2020-10-17 11:54:14 -0400 |
---|---|---|
committer | Jason R. Coombs <jaraco@jaraco.com> | 2020-10-17 11:54:14 -0400 |
commit | b7c83dad9e11fbbc2a69fcc5fc26d4c7d1f5551f (patch) | |
tree | 6e44ffdf5ee615d3a845106e3a51c172b2dedce0 /changelog.d/README.rst | |
parent | b66e45a90e82c9170cc48f21e4dac9d206193953 (diff) | |
parent | 61e61296d9537c3e82516611ec283e42b1ed0466 (diff) | |
download | python-setuptools-git-b7c83dad9e11fbbc2a69fcc5fc26d4c7d1f5551f.tar.gz |
Merge branch 'master' into patch-1
Diffstat (limited to 'changelog.d/README.rst')
-rw-r--r-- | changelog.d/README.rst | 94 |
1 files changed, 94 insertions, 0 deletions
diff --git a/changelog.d/README.rst b/changelog.d/README.rst new file mode 100644 index 00000000..30831edc --- /dev/null +++ b/changelog.d/README.rst @@ -0,0 +1,94 @@ +.. _Adding change notes with your PRs: + +Adding change notes with your PRs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +It is very important to maintain a log for news of how +updating to the new version of the software will affect +end-users. This is why we enforce collection of the change +fragment files in pull requests as per `Towncrier philosophy`_. + +The idea is that when somebody makes a change, they must record +the bits that would affect end-users only including information +that would be useful to them. Then, when the maintainers publish +a new release, they'll automatically use these records to compose +a change log for the respective version. It is important to +understand that including unnecessary low-level implementation +related details generates noise that is not particularly useful +to the end-users most of the time. And so such details should be +recorded in the Git history rather than a changelog. + +Alright! So how to add a news fragment? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``setuptools`` uses `towncrier <https://pypi.org/project/towncrier/>`_ +for changelog management. +To submit a change note about your PR, add a text file into the +``changelog.d/`` folder. It should contain an +explanation of what applying this PR will change in the way +end-users interact with the project. One sentence is usually +enough but feel free to add as many details as you feel necessary +for the users to understand what it means. + +**Use the past tense** for the text in your fragment because, +combined with others, it will be a part of the "news digest" +telling the readers **what changed** in a specific version of +the library *since the previous version*. You should also use +reStructuredText syntax for highlighting code (inline or block), +linking parts of the docs or external sites. +If you wish to sign your change, feel free to add ``-- by +:user:`github-username``` at the end (replace ``github-username`` +with your own!). + +Finally, name your file following the convention that Towncrier +understands: it should start with the number of an issue or a +PR followed by a dot, then add a patch type, like ``change``, +``doc``, ``misc`` etc., and add ``.rst`` as a suffix. If you +need to add more than one fragment, you may add an optional +sequence number (delimited with another period) between the type +and the suffix. + +In general the name will follow ``<pr_number>.<category>.rst`` pattern, +where the categories are: + +- ``change``: Any backwards compatible code change +- ``breaking``: Any backwards-compatibility breaking change +- ``doc``: A change to the documentation +- ``misc``: Changes internal to the repo like CI, test and build changes +- ``deprecation``: For deprecations of an existing feature or behavior + +A pull request may have more than one of these components, for example +a code change may introduce a new feature that deprecates an old +feature, in which case two fragments should be added. It is not +necessary to make a separate documentation fragment for documentation +changes accompanying the relevant code changes. + +Examples for adding changelog entries to your Pull Requests +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +File :file:`changelog.d/2395.doc.1.rst`: + +.. code-block:: rst + + Added a ``:user:`` role to Sphinx config -- by :user:`webknjaz` + +File :file:`changelog.d/1354.misc.rst`: + +.. code-block:: rst + + Added ``towncrier`` for changelog managment -- by :user:`pganssle` + +File :file:`changelog.d/2355.change.rst`: + +.. code-block:: rst + + When pip is imported as part of a build, leave :py:mod:`distutils` + patched -- by :user:`jaraco` + +.. tip:: + + See :file:`pyproject.toml` for all available categories + (``tool.towncrier.type``). + +.. _Towncrier philosophy: + https://towncrier.readthedocs.io/en/actual-freaking-docs/#philosophy |