101 lines
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/ 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/ release <name-of-the-release>
The command will do the following:
1. Move all log entries from `unreleased` to the new release folder
2. Add a meta entry to the `releases.json` file
3. Generate a new ``
After you made a release you can move the `` file to the root of the project.
## Additional commands
### Purge
python3 ./src/ purge
This command will delete:
- generated ``
- `entries` directory
- `releases.json`
Be careful when running `purge` since it will delete these files permanently!
### Generate
python3 ./src/ generate
This command will generate a new `` 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 ``
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 file manually?
No. The 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/ generate`