Changelog Entries

If your change is noteworthy, there needs to be a changelog entry so our users can learn about it!

To avoid merge conflicts, we use the towncrier package to manage our changelog. towncrier uses independent files for each pull request – called news fragments – instead of one monolithic changelog file. On release, those news fragments are compiled into our doc/CHANGELOG.rst.

You don’t need to install towncrier yourself, you just have to abide by a few simple rules:

  • For each pull request, add a new file into news/ with a filename adhering to the pr#.(feature|bugfix|breaking).rst schema: For example, news/42.feature.rst for a new feature that is proposed in pull request #42.

    Our categories are: feature, bugfix, breaking (breaking changes), deprecation, hooks (all hook-related changes), bootloader, moduleloader, doc, process (project infrastructure, development process, etc.), core, build (the bootloader build process), and tests.

  • As with other docs, please use semantic newlines within news fragments.

  • Prefer present tense or constructions with “now” or “new”. For example:

    • Add hook for my-fancy-library.

    • Fix crash when trying to add resources to Windows executable using --resource option.

    If the change is relevant only for a specific platform, use a prefix, like here:

    • (GNU/Linux) When building with --debug turn of FORTIFY_SOURCE to ease debugging.

  • Wrap symbols like modules, functions, or classes into double backticks so they are rendered in a monospace font. If you mention functions or other callables, add parentheses at the end of their names: is_module(). This makes the changelog a lot more readable.

  • If you want to reference multiple issues, copy the news fragment to another filename. towncrier will merge all news fragments with identical contents into one entry with multiple links to the respective pull requests. You may also reference to an existing newsfragment by copying that one.

  • If your pull-request includes several distinct topics, you may want to add several news fragment files. For example 4242.feature.rst for the new feature, 4242.bootloader for the accompanying change to the bootloader.

Remember that a news entry is meant for end users and should only contain details relevant to an end user.