Estimated reading time: 3 minutes

Changelog Fragments#

The root changelog/ directory contains towncrier news fragment files. Each file represents a single changelog entry for the next release.

Fragment File Naming#

Files must be named as:

<PR-number>.<type>.rst

Where <PR-number> is the pull request number and <type> is one of the following fragment types:

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.

Fragment File Content#

Each file should contain a short reStructuredText description of the change. For example, a file named 7146.feature.rst might contain:

:user:`bjlittle` extended the :meth:`~iris.coords.Coord.cell` and
:meth:`~iris.coords.Coord.cells` methods to allow users to specify that
they want :class:`~datetime.datetime` compatible objects returned within
each generated :class:`~iris.coords.Coord.Cell` from a temporal
coordinate. (:issue:`7112`)

Notes#

  • You do not need to include the PR number in the fragment as it is already in the fragment filename.

  • Multiple fragments may reference the same PR number if the PR makes changes across different categories.

  • For multiple PRs that reference the same change, simply create a separate changlog fragment file for each PR with identical contents.

  • Use :issue:`NNNN` for issue references, :pull:`NNNN` for PR references, and :user:`github-name` for user references.

  • The rendered changelog can be previewed with:

    > towncrier build --draft

  • The changelog can be published with:

    > cd docs/src/whatsnew
> mkdir <major.minor>
> git mv highlights.rst <major.minor>
> towncrier build --version <major.minor>

  • For further details see the Command Line Reference for towncrier.