6.4. Adding a Changelog Entry¶
A “Changelog” is a record of all notable changes made to a project. Such
a changelog, in our case the
CHANGELOG.rst, is read by our users.
Therefor, any description should be aimed to users instead of describing
internal changes which are only relevant to developers.
To avoid merge conflicts, we use the Towncrier package to manage our changelog.
changelog.d contains “newsfragments” which are short
On release, those news fragments are compiled into our
You don’t need to install
towncrier yourself, use the tox command
to call the tool.
We recommend to follow the steps to make a smooth integration of your changes:
After you have created a new pull request (PR), add a new file into the directory
changelog.d. Each filename follows the syntax:
<ISSUE>is the GitHub issue number. In case you have no issue but a pull request, prefix your number with
<TYPE>is one of:
bugfix: fixes a reported bug.
deprecation: informs about deprecation warnings
doc: improves documentation.
feature: adds new user facing features.
removal: removes obsolete or deprecated features.
trivial: fixes a small typo or internal change that might be noteworthy.
Create the new file with the command:
tox -e changelog -- create 123.feature.rst
The file is created int the
Open the file and describe your changes in RST format.
Wrap symbols like modules, functions, or classes into double backticks so they are rendered in a
Prefer simple past tense or constructions with “now”.
Check your changes with:
tox -e changelog -- check
Optionally, build a draft version of the changelog file with the command:
tox -e changelog
Commit all your changes and push it.
This finishes your steps.
On release, the maintainer compiles a new
CHANGELOG.rst file by running:
tox -e changelog -- build
This will remove all newsfragments inside the
making it ready for the next release.