Thoughts on Changelogs
Some time ago at work someone suggested we start using a template for our
commit messages, based on what the Angular project does.
The rules are documented in the CONTIRBUTING.md page on github.
In a nutshell, here’s what the commit messages look like:
* feat($anchorScroll): convert numeric hash targets to string * docs(ngCsp): fix "directive"'s `restrict` and hide comment from output * refactor($resource): use `route.defaults` (already merged `provider.defaults` + `options`)
We decided to start using this too, and someone on the team said: “Great! That way we can use a script to generate changelogs!”
Keep a CHANGELOG #
Some one on the Internet1 already said it: Don’t let your friends dump git logs into CHANGELOGs™
Feel free to read the page, there’s tons of helpful advice.
Here’s what the authors say about just using git log messages:
Why can’t people just use a git log diff?
Because log diffs are full of noise — by nature. They could not make a suitable change log even in a hypothetical project run by perfect humans who never make typos, never forget to commit new files, never miss any part of a refactoring. The purpose of a commit is to document one atomic step in the process by which the code evolves from one state to another. The purpose of a change log is to document the noteworthy differences between these states.
Put in an other way : git log messages are useful amongts developers inside
your project. They’ll use the git log to understand why a particular change
was made, either during review, or when they run
git blame on a file.
On the other hand, the changelog is meant to help developers outside the project. They’ll use it to understand why something broke after they upgrade, or simply when they try to figure out if it’s worth upgrading at all.
Since the target audience of the git log messages and the changelog are so different, I believe you simply can’t use one to generate the other.
Some changelog tips #
Here are a few additional tips I’d like to share.
The items in the git log messages are of course always sorted chronologically. 2
In a changelog, sections are also sorted chronologically, but inside a section, you may want to sort them in a different order, like so:
# Version 3.0 (2016-10-01) ## Highlights * Some new feature here <link to the documentation> * A critical security bug fix there <link to the CVE> ## Other Bug fixes * A minor bug fix here <link to the bug> ## Breaking changes
That’s an other good reason why you can’t directly use git log messages for this. (I’m not a big fan of sections named “added”, “removed”, “changed”, “fixed”, but your mileage may vary)
When to update the Changelog #
The page also says:
Always have an “Unreleased” section at the top for keeping track of any changes.
This serves two purposes:
People can see what changes they might expect in upcoming releases
At release time, you just have to change “Unreleased” to the version number and add a new “Unreleased” header at the top.
It’s easy to enforce this during code review: when someone commits something that is worth documenting for the outside users, make them update the changelog in the same commit, or in a commit right after it.
If you wait until right before publishing a new release, you may have a hard time remembering exactly what changed and why.
Also, by forcing people to update the changelog when they break retro-compatibility (which is one of the most valuable things to have in a changelog), you’ll have an opportunity to:
- Make sure the breaking change is properly documented (aka: what will I have to fix if I upgrade?)
- Discuss whether a backward-compatibility layer may be implemented.
Using the Changelog #
Making a new release of any project is exciting, and you’re eager to tell the world about it.
But, please, when this occurs, include a link to your changelog in your annoncement!
It really bothers means when I see a
foo 1.3 is out! on twitter or on a
mailing list but with no links to the actual Changelog at all.
See you next time!
Olivier Lacan, to be precise :) ↩︎
Well, almost. You can amend your commits and change the date any way you like. ↩︎
Thanks for reading this far :)
I'd love to hear what you have to say, so please feel free to leave a comment below, or read the contact page for more ways to get in touch with me.
Note that to get notified when new articles are published, you can either:
- Subscribe to the RSS feed or the newsletter
- Or follow me on Mastodon, dev.to, or twitter.