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
package to manage our changelog.
uses independent files for each pull request – called
– instead of one monolithic changelog file. On release, those news fragments are compiled into our
You don’t need to install
yourself, you just have to abide by a few simple rules:
For each pull request, add a new file into
with a filename adhering to the
schema: For example,
for a new feature that is proposed in pull request #42.
Our categories are:
(all hook-related changes),
(project infrastructure, development process, etc.),
(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:
If the change is relavant only fo a specific platform, use a prefix, like here:
--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:
. This makes the changelog a lot more readable.
If you want to reference multiple issues, copy the news fragment to another filename.
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
for the new feature,
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.