Changelog Manager helps you generate a CHANGELOG.md file for your Git repo
that adheres to the Keep A Changelog standard,
and doesn't result in almost constant conflicts.
There are tons of great reasons to Keep A Changelog. We found that having a Changelog file for our app helped everyone in the organization to know what was in the upcoming release, but requiring developers to add lines to it with every PR resulted in constant git conflicts. Changelog Manager solves that.
When your want to add a new entry to the changelog Changelog Manager will ask
you some quick questions and store a JSON file in the .changelog_entries
folder of your project. Then, when your ready, it will generate a full
CHANGELOG.md organizing everything by tag and change type.
There are a lot of solutions out there that offer this. There are a few problems with this
- Commit messages are too fine grained and frequently very geeky
- The Ticket / Story is typically the correct level of abstraction and their titles are rarely appropriately worded for Changelog entries
- and many, many more reasons.
To add a new entry just invoke it.
changelog_manager
It will ask you a series of questions and generate a new file in
.changelog_entries That file will be used when generating the full
CHANGELOG.md file.
If you project uses a ticket tracker you can configure it so that it will generate the url to the ticket without asking.
By default new changelog entry will be added to git (but not committed) upon creation. This can be changed as part of the configuration
The Changelog version numbers are extracted from git tags. The presumption is
that your repo will be tagged using semantically versioned numbers that can
optionally begin with a "v" for example v1.0.1 and 1.0.1 are both acceptable
version numbers to the changelog_manager.
To generate a new CHANGELOG.md just invoke it with the -c parameter (or
--compile). The changelog is printed to STDOUT so that you can shove it into
a file or run it through a Markdown -> HTML conversion, or whatever else you
want to do with it.
chagelog_manager -c > CHANGELOG.md
Developers dun awlayz write gud.
In our experience developers tend to write Changelog entries at the wrong level of abstraction. E.g. To damn geeky. We need to tweak them to make sense to the non-geeks consuming the changelog. Sometimes, we just want to fix typos.
If you see a changelog entry that needs adjusting
- Find the appropriate file in
.changelog_entries- If there's a ticken number grep for it.
- If not, just grep for a short bit of the changlog entry
grep "some text" .changelog_entries/*
- Open the file in your favorite text editor, and edit it.
- Must remain valid JSON.
- Add and Commit the changes to git.
It doesn't matter that the entry was created with an old commit.
changelog_manager will always generate CHANGELOG.md from the latest version
of files found in .commit_entries. I.e.
"new hotness", not "old and busted".
Note: in the utils directory you will find a description_by_file bash
script. Run this within the home directory of your app and it'll generate a
listing of the JSON files and the description in each. For example:
$ description_by_file
.changelog_entries/101b2bc9f12ab533da6dd9957308fec1.json new entry creation now honors git_add setting in config file
.changelog_entries/1857d1f1ef88830d500227dd2b135f07.json Improved readme, added link to download the latest pre-compiled version
You can then pipe that output through grep, or whatever to find the one you're looking for. Suggestions for improving the editing experience will be welcomed.
Changelog Manager some optional configurations you will want to check out.
You can download changelog_manager for macOS
here.
Just decompress it tar -xzf changelog_manager.tgz and add it to your path.
Then follow the Usage guidelines.
See troubleshooting if you have problems with the downloaded binary.
Checkout the instructions here
- [masukomi] masukomi - creator, maintainer