💾 Archived View for dmerej.info › en › blog › 0023-thoughts-on-changelogs.gmi captured on 2023-01-29 at 16:10:10. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2022-07-16)
-=-=-=-=-=-=-
2016, Oct 01 - Dimitri Merejkowsky License: CC By 4.0
Some time ago at work someone suggested we start using a template for our `git` commit messages, based on what the Angular project[1] does.
The rules are documented in the CONTIRBUTING.md page[2] on github.
2: https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit-message-format
In a nutshell, here's what the commit messages look like:
We decided to start using this too, and someone on the team said: "Great! That way we can use a script to generate changelogs!"
Some one on the Internet 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.
Here are a few additional tips I'd like to share.
The items in the git log messages are of course always sorted chronologically.
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
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)
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:
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!
----