Adding News Fragments#

If your pull request introduces a significant change, add a news fragment file with a high-level summary of your contribution. These fragments are collected to automatically generate the project’s Changelog for each new release.

It needs the Towncrier tool to manage news fragment files that are assembled into a changelogs later. The tool is installed automatically when you prepare your environment.

Note

Using the Towncrier tool

While you can create news fragment files manually, using the towncrier create command is highly recommended. It helps prevent common mistakes, such as using an invalid fragment type, and ensures the filename follows the correct format.

We recommend to follow the steps to make a smooth integration of your changes after you have created a new pull request (PR):

  1. Make yourself familiar with the syntax of the news fragments. Each filename follows the syntax:

    <ISSUE>.<TYPE>.rst

    where <ISSUE> is the GitHub pull request or issue number. If you have changes that are not associated with an issue or pull request, start with a + (plus) sign and a short description The <TYPE> is one of:

    • breaking: describes a change that breaks backward compatibility.

    • bugfix: fixes a reported bug.

    • deprecation: informs about deprecation or removed features.

    • doc: improves documentation.

    • feature: adds new user facing features.

    • refactor: refactors code without changing the user facing API.

    • removal: removes obsolete or deprecated features.

    • infra: improves the infrastructure, e.g. build or test system.

    For example, these are valid filenames: 123.feature.rst, 456.bugfix.rst, +add-json.feature.rst etc.

  2. Create the new file with the command, for example for a feature in issue 123:

    Create a new newsfragment file#
    towncrier create -c "Description" 123.feature.rst

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

  3. If neccessary, open the file and describe your changes in RST format.

    • Wrap symbols like modules, functions, or classes into double backticks to render them in a monospace font.

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

    Try to keep the description short.

  4. Check your changes:

    towncrier check

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

    towncrier build --draft

  6. Commit all your changes and push it.

This finishes your steps.