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
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
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).rstschema: For example,
news/42.feature.rstfor a new feature that is proposed in pull request #42.
Our categories are:
hooks(all hook-related changes),
process(project infrastructure, development process, etc.),
build(the bootloader build process), and
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
If the change is relavant only fo a specific platform, use a prefix, like here:
- (GNU/Linux) When building with
--debugturn 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.
towncrierwill 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.rstfor the new feature,
4242.bootloaderfor 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.