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:
Ensure there is an issue in the bug tracker that describes the context of the change.
Before merging a PR, ensure a news fragment describing the change is added to the
changelog
directory.Its file name should follow
<issue_number>.<resolution>.md
, whereresolution
is one of the following:fixed
added
changed
removed
deprecated
security
The file contents should be written in Markdown.
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. Refer to Building the changelog for instructions on how to do this.