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.

The directory changelog.d contains “newsfragments” which are short ReST-formatted files. On release, those news fragments are compiled into our CHANGELOG.rst.

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:

  1. After you have created a new pull request (PR), add a new file into the directory changelog.d. Each filename follows the syntax:

    <ISSUE>.<TYPE>.rst

    where <ISSUE> is the GitHub issue number. In case you have no issue but a pull request, prefix your number with pr. <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.

    For example: 123.feature.rst, pr233.removal.rst, 456.bugfix.rst etc.

  2. Create the new file with the command:

    tox -e changelog -- create 123.feature.rst

    The file is created int the changelog.d/ directory.

  3. 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 monospace font.

    • Prefer simple past tense or constructions with “now”.

  4. Check your changes with:

    tox -e changelog -- check

  5. Optionally, build a draft version of the changelog file with the command:

    tox -e changelog

  6. 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 changelog.d directory, making it ready for the next release.