The Heist-Salt project uses the towncrier tool to manage the CHANGELOG.md file.
Theis tool helps manage the changelog and help prevent merge conflicts when managing
one file. This tool adds changelog entries into separate files and before a release
we simply need to run
towncrier --version=<version> for it to compile the
How do I add a changelog entry#
To add a changelog entry you will need to add a file in the changelog directory.
The file name should follow the syntax
The types are in alignment with keepachangelog:
any features that have been removed
any features that will soon be removed
any changes in current existing features
any bug fixes
any new features added
For example if you are fixing a bug for issue number #1234 your filename would
look like this: changelog/1234.fixed. The contents of the file should contain
a summary of what you are fixing. If there is a legitimate reason to not include
an issue number with a given contribution you can add the MR number as the file
If your MR does not align with any of the types, then you do not need to add a changelog entry.
How to generate the changelog#
This step is only used when we need to generate the changelog right before releasing. You should NOT run towncrier on your MR, unless you are preparing the final MR to update the changelog before a release.
You can run the towncrier tool directly or you can use nox to help run the command and ensure towncrier is installed in a virtual environment. The instructions below will detail both approaches.
If you want to see what output towncrier will produce before generating the change log you can run towncrier in draft mode:
towncrier --draft --version=3001
nox -e 'changelog(draft=True)' -- 3000.1
Version will need to be set to whichever version we are about to release. Once you are confident the draft output looks correct you can now generate the changelog by running:
nox -e 'changelog(draft=False)' -- 3000.1
After this is run towncrier will automatically remove all the files in the changelog directory.