Contributing a “What’s New” Entry#

Estimated reading time: 7 minutes

Please include a “What’s New” changelog fragment for any change that you make to Iris. Even if it is not relevant to users - the Fragment Types include internal for this - the page is read by contributors as well as users, and it reveals the work needed to keep a project going.

Iris uses towncrier to manage changelog entries. Each pull request adds a small file (a “fragment”) to the root changelog/ directory. At release time, towncrier collects the fragments and renders the full What’s New page.

See this docs section for all What’s New pages: What’s New in Iris.

How it Works#

Instead of editing a shared file, each contributor creates a small reStructuredText file in the changelog/ directory at the root of the repository. This avoids the merge conflicts that were common with the previous approach.

Creating a Fragment#

  1. Name your file using the pattern:

    <PR-number>.<type>.rst

    For example, if your pull request number is 7200 and you are adding a feature, create:

    changelog/7200.feature.rst

    Hint

    If you have not yet created the pull request, you can guess what the next PR number may be using:

    > curl -s "https://api.github.com/repos/SciTools/iris/issues?sort=created&direction=desc&per_page=1" | jq -r '.[0].number + 1'

  2. Write a short description of your change in the file. The content is reStructuredText. For example:

    :user:`tkknight` added a new option to :func:`iris.plot.pcolormesh`
for controlling the colorbar orientation. (:issue:`9999`)

    Notes:

    • Use :user:`github-name` to credit contributors.

    • Use :issue:`NNNN` to reference issues.

    • The pull request reference is added automatically by towncrier based on the fragment filename - you do not need to include :pull: in your content unless you are referencing another pull request.

    • Where possible, do not exceed column 80.

  3. Multiple fragments per PR are allowed if a single pull request makes changes across different categories. For example, a PR might have both 7200.feature.rst and 7200.doc.rst. If multiple fragments within the same category are needed, you can append .0.rst, .1.rst, etc to the end of the file.

  4. Multiple PRs per fragment are automatically collated by towncrier. Create separate fragment files per PR with identical contents.

Fragment Types#

The following fragment types are available, matching the rendered section headings in the What’s New page:

announcement

📢 General news and announcements to the Iris community.

feature

✨ Features that are new or changed to add functionality.

bugfix

🐛 A bug fix.

breaking

💣 A change that causes an incompatibility with prior versions of Iris.

performance

🚀 A performance enhancement.

deprecation

🔥 Deprecation of functionality.

dependency

🔗 Additions, removals and version changes in Iris’ package dependencies.

doc

📚 Changes to documentation.

internal

💼 Changes to any internal or development related topics, such as testing, environment dependencies etc.

Highlights#

The release highlights associated with a towncrier changelog are defined in the docs/src/whatsnew/highlights.rst file.

Manually update the hightlights.rst with any notable release information that you want to share with the community.

Previewing the Changelog#

You can manually preview how the changelog will render by running:

> towncrier build --draft

This will print the rendered reStructuredText to stdout without modifying any files or removing fragment files.

Note

The reStructuredText syntax will be checked as part of building the documentation. Any warnings should be corrected. The Iris GitHub Actions will automatically build the documentation when creating a pull request, however you can also manually build the documentation.

Tip

towncrier and the sphinx-changlog directive will automatically render the latest development changelog whenever the documentation is built.

Building the Changelog#

To build the release changelog

  1. Change directory to docs/src/whatsnew/.

  2. Ensure that the hightlights.rst is populated.

  3. Create the changelog release directory e.g., mkdir <major.minor>.

  4. Relocate the hightlights.rst i.e., git mv highlights.rst <major.minor>.

  5. Build the changelog i.e., towncrier build --version <major.minor>. Note that this will create a rendered <major.minor>/<major.minor>.rst changelog and automatically stage this file with git. The changelog news fragment files will also be automatically removed.

  6. Remove the latest development changelog i.e., git rm latest.rst.

  7. Update the “What’s New” index.rst replacing all references to latest.rst with <major.minor>/<major.minor>.rst.

Tip

Using the --keep command line argument when building the changelog allows you to review the rendered release changelog and keep all the changelog news fragment files, allowing you to backtrack and make changes, if necessary.

Configuration#

towncrier is configured within the [tool.towncrier] table of the root pyproject.toml.

The changelog/template.rst file contains the jinja2 template used by towncrier to render the changelog news fragments, sections, title and include the associated hightlights.rst.