masukomi/changelog_manager: A tool to let a team add CHANGELOG entries without constant conflicts.

Why Use It

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.

Background

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 you 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 (see How It Works). Then, when you’re ready, it will generate a full CHANGELOG.md file, organizing everything by tag and change type.

Why not auto-generate them from Commits or PRs?

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.

How to use it

Adding a new entry

To add a new entry just invoke it on the command line with no arguments:

changelog_manager

It will ask you a series of questions and generate a new file in .changelog-entries (see How It Works). 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 requiring you to manually enter it.

Git Integration

New Entries

By default new changelog entry will be added to git (but not committed) upon creation. This can be changed as part of the configuration of the Changelog Manager.

Changelog Generation

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.

Generating a new CHANGELOG.md

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

Filtered CHANGELOG.md generation

Changelog entries can be "tagged" with metadata during their creation (think tagging bookmarks, not git tags). For example, if you have a security issue that you've fixed, but should remain internal only, you might tag it with "internal". You might have some items that are specific to one of your clients, so you’d tag those with "client_a" or "client_b".

Then, when you generate the Changelog, you can choose which tags should be included in the output. The following command would generate a changelog with generic (untagged) items, and items tagged with "client_a" but no "internal" or "client_b" tags.

changelog_manager -c -w client_a > CHANGELOG.md

You can specify multiple tags by providing a comma separated list to -w for example changelog_manager -c -w internal,awesome

Editing an entry

Developers dun awlayz write gud.

In our experience, developers tend to write Changelog entries at the wrong level of abstraction. E.g. Too 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 Changelog entry
- grep "some text" .changelog_entries/*
Open the file in your favorite text editor, and edit it.
- Must remain valid JSON.
- Yes, we can, and should make this easier.
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.

Configuration

Changelog Manager some optional configurations you will want to check out.

How To Get It

Unfortunately, right now the best way is to build from source. Homebrew install coming (hopefully) soon.

Building from source

Changelog Manager is written in Crystal so, you'll need to install the Crystal compiler.

The run_me_first.sh script will take care of installing that, and the libraries it needs if you're on a system with homebrew. If not it'll list what you need.

Clone this repo.
on the command line run ./run_me_first.sh

if you're on a system without homebrew, you'll need to manually install the libraries it tells you it needs.

on the command line run ./build.sh

This will generate a changelog_manager executable in the current directory.

Put the new changelog_manager file somewhere in your path. Here's how to add a directory to your path. Or, if you just run echo $PATH on the command line you can simply move changelog_manager to any of the directories in that list (that you have write access to).

That's it.

What you should put in it

So we’ve covered how to use the Changelog Manager tool, but how do you write a useful changelog entry?

Bottom line: your changelog entry should be human-readable by your target audience.

In some cases, the changelog may only ever be viewed by other developers, so writing geeky details in it may be exactly the use case you need.

In other cases, your changelog may be read by a non-developer who may need to communicate about the awesome work you’re doing to other non-developers.

That means you need to find the right level of abstraction to discuss what your commit contains, and to do it using language that your audience will understand.

If your changelog is intended for consumption by non-developers, think of it this way. A non-developer isn’t familiar with the source, specific integrations, or functions, and as such, has no way to understand your changes unless you find a plain-language way to tell them. And writing that clearly in a changelog entry saves the time later of that non-developer having to hunt you down and ask you about the commit, which then turns into a 15-minute conversation about all the things.

So let’s just head that off now with a useful Changelog entry.

What's not a good Changelog entry

Monkey see, monkey do. Here are a few examples of what NOT to write in your changelog entries:

Changed Method X
- Non-geeks will have no clue
Added support for X technology
- Why? To what end?
Fixed bug on X page
- What bug?
Updated Foo Report
- What did you update about it?

What you should put in it

If you checked out the link at the top of the doc to Keep a Changelog this is going to look very familiar to you. A good changelog should:

Be human-readable using language your target audience will understand
The Changelog Manager tool will ask you what kind of change you’ve made so that others can understand their impact on the project, as follows:
Added for new features.
- Changed for changes in existing functionality.
- Deprecated for once-stable features removed in upcoming releases.
- Removed for deprecated features removed in this release.
- Fixed for any bug fixes.
- Security to invite users to upgrade in case of vulnerabilities.

You may have multiple changelog entries for a single piece of work, because each entry should describe only one of these types of changes; i.e. you’d have separate entries for Added new features vs. Removed deprecated features. In this example, you’d run the changelog_manager tool twice.

From a practical standpoint, there are a couple of good rules that can help you make sure you’re writing a useful, human-readable changelog entry:

Don’t use internal jargon. If a bug is fixed, speak in terms of the actions that caused it, or the behavior it exhibited, but not the specific classes, unless you absolutely have to.
It must be knowledge that’s useful to your users. Speak to the features and flaws that affect your customers. Users don’t care that you refactored some unit test, or reformatted your comments.

And finally, here are a few examples: