3.3 KiB
Changelog Generator
This util allows you to generate changelog entries without causing merge conflicts.
Getting started
Setup environment
Go into the changelog
folder and run the following commands
Create virtual environment
python3 -m venv venv
Activate environment
source venv/bin/activate
Install dependencies
python3 -m pip install -r requirements.txt
Add a new entry
python3 ./src/changelog.py add
The command will ask you for the required information to create a new changelog entry.
The entry will then be added to the unreleased
folder as a .json
file.
You can edit any .json
file directly as well, the commands only exist to simplify
your workflow.
Make a release
python3 ./src/changelog.py release <name-of-the-release>
The command will do the following:
- Move all log entries from
unreleased
to the new release folder - Add a meta entry to the
releases.json
file - Generate a new
changelog.md
After you made a release you can move the changelog.md
file to the root of the project.
Additional commands
Purge
python3 ./src/changelog.py purge
This command will delete:
- generated
changelog.md
entries
directoryreleases.json
Be careful when running purge
since it will delete these files permanently!
Generate
python3 ./src/changelog.py generate
This command will generate a new changelog.md
file without making a new release.
FAQ
Why do we need this tool?
Before we used this tool we just added changelog entries manually to the changelog.md
which lead to us having regular merge conflicts when multiple people would add a log
of the same type during the same release cycle. Those conflicts were annoying and
ate up pipeline minutes.
Can you edit the logs manually?
Yes, every log file and any meta files are editable and can be edited if a mistake was made during the generation process.
Can you edit the changelog.md file manually?
No. The changelog.md file is generated automatically and should never be edited directly. Any change you make to the file will be deleted when it's regenerated.
What determines the order of the releases in the changelog?
The order is determined by the order of the releases inside releases.json
. If you wish
to change the order you will have to move the release inside the releases
array to
the desired position.
Should I commit my changelog entries?
Yes, every changelog entry should be committed as part of your MR.
Can I add bullet points to my entry?
Yes, you can. If you need to add bullet points for when new templates are created for
example, you can do so by adding your bullet point strings to the bullet_points
list
of a changelog entry.
You can only do this by directly editing the .json
file at the moment since it's a
fringe use case and wouldn't make sense to add as a prompt when creating the entry
via the CLI.
What should I do if I need to make changes to an existing release?
If you have generated a new release, and you notice afterwards that you meant to change
one of the entries before making the release you can change the content of the changelog
entry in the JSON file directly and then run python3 ./src/changelog.py generate