Keeping a changelog

Your Saltext project uses towncrier to manage and render its CHANGELOG.md file, which is included in the rendered documentation as well.

Hint

If you selected deploy_docs == rolling, the changelog will display upcoming changes from the main branch alongside crystallized changes from previous releases.

Procedure

For every user-facing change, ensure your patch includes a corresponding news fragment:

  1. Ensure there is an issue in the bug tracker that describes the context of the change.

  2. Before merging a PR, ensure a news fragment describing the change is added to the changelog directory.

  3. Its file name should follow <issue_number>.<resolution>.md, where resolution is one of the following:

    • fixed

    • added

    • changed

    • removed

    • deprecated

    • breaking

    • security

  4. The file contents should be written in Markdown and need to render to a list item in the changelog, so keep it short and avoid newlines.

Hint

It’s possible to create a news fragment that does not reference an issue by prefixing the file name with a +, e.g. +foo.changed.md.

Example

Suppose a PR fixes a crash when the foo.bar configuration value is missing. The news fragment can be created as follows:

echo "Fixed a crash when 'foo.bar' is missing from the configuration" > changelog/23.fixed.md

Include this file in the PR.

Building the changelog

Before tagging a release, the individual changelog/*.md files need to be compiled into the actual changelog. This is taken care of by the release automation. For manual releases, refer to Building the changelog for instructions on how to do this.