1.. _Adding change notes with your PRs:
2
3Adding change notes with your PRs
4^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5
6It is very important to maintain a log for news of how
7updating to the new version of the software will affect
8end-users. This is why we enforce collection of the change
9fragment files in pull requests as per `Towncrier philosophy`_.
10
11The idea is that when somebody makes a change, they must record
12the bits that would affect end-users only including information
13that would be useful to them. Then, when the maintainers publish
14a new release, they'll automatically use these records to compose
15a change log for the respective version. It is important to
16understand that including unnecessary low-level implementation
17related details generates noise that is not particularly useful
18to the end-users most of the time. And so such details should be
19recorded in the Git history rather than a changelog.
20
21Alright! So how to add a news fragment?
22^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
23
24``setuptools`` uses :pypi:`towncrier` for changelog management.
25To submit a change note about your PR, add a text file into the
26``changelog.d/`` folder. It should contain an
27explanation of what applying this PR will change in the way
28end-users interact with the project. One sentence is usually
29enough but feel free to add as many details as you feel necessary
30for the users to understand what it means.
31
32**Use the past tense** for the text in your fragment because,
33combined with others, it will be a part of the "news digest"
34telling the readers **what changed** in a specific version of
35the library *since the previous version*. You should also use
36reStructuredText syntax for highlighting code (inline or block),
37linking parts of the docs or external sites.
38If you wish to sign your change, feel free to add ``-- by
39:user:`github-username``` at the end (replace ``github-username``
40with your own!).
41
42Finally, name your file following the convention that Towncrier
43understands: it should start with the number of an issue or a
44PR followed by a dot, then add a patch type, like ``change``,
45``doc``, ``misc`` etc., and add ``.rst`` as a suffix. If you
46need to add more than one fragment, you may add an optional
47sequence number (delimited with another period) between the type
48and the suffix.
49
50In general the name will follow ``<pr_number>.<category>.rst`` pattern,
51where the categories are:
52
53- ``change``: Any backwards compatible code change
54- ``breaking``: Any backwards-compatibility breaking change
55- ``doc``: A change to the documentation
56- ``misc``: Changes internal to the repo like CI, test and build changes
57- ``deprecation``: For deprecations of an existing feature or behavior
58
59A pull request may have more than one of these components, for example
60a code change may introduce a new feature that deprecates an old
61feature, in which case two fragments should be added. It is not
62necessary to make a separate documentation fragment for documentation
63changes accompanying the relevant code changes.
64
65Examples for adding changelog entries to your Pull Requests
66^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
67
68File :file:`changelog.d/2395.doc.1.rst`:
69
70.. code-block:: rst
71
72    Added a ``:user:`` role to Sphinx config -- by :user:`webknjaz`
73
74File :file:`changelog.d/1354.misc.rst`:
75
76.. code-block:: rst
77
78    Added ``towncrier`` for changelog management -- by :user:`pganssle`
79
80File :file:`changelog.d/2355.change.rst`:
81
82.. code-block:: rst
83
84    When pip is imported as part of a build, leave :py:mod:`distutils`
85    patched -- by :user:`jaraco`
86
87.. tip::
88
89   See :file:`pyproject.toml` for all available categories
90   (``tool.towncrier.type``).
91
92.. _Towncrier philosophy:
93   https://towncrier.readthedocs.io/en/actual-freaking-docs/#philosophy
94