Writing Release Notes with git log
When I make pull requests, I encourage the use of a leading: “FEATURE” or “FIX” along with Chris Beams post
I followed it because for those reasons, it makes sense. “Future me” really appreciates the thought “past me” put into writing a better pull request message. The change is either a feature or a fix, right?!
Immediate Use Cases
Most of the time, the benefit of this messaging is only immediate, in the email subject line.
Another moment where this benefit is apparent is debugging: “Interesting, this is a feature/fix change…” but this is not as frequent, nor as beneficial..
Release Notes
I found another time where this messaging format is beneficial: writing release notes!
If you hate writing documentation, writing release notes will probably drive you up the wall. Release notes are basically documentation on code in between the current release and the last release.
If the repository has tags for each release, then tracking changes
between releases using git is trivial. $ git diff <past> <current>
is sufficient.
How about writing the release notes?
Writing release notes from just code changes is would be an incredible human feat. (and if you can do that, contact me, I’m hiring! :-) )
Release Notes from Pull Request Messages
Instead of writing the release notes from that’s where the pull request message comes in.
Retrieve messages using:
On a repository where every commit message starts with FEATURE or FIX, the results will look like:
- FIX: Remove Spirit hands (#123)
- FEATURE: Add rubocop gem (#125)
- FIX: Optimize serializer performance (#132)
- Merge pull request #134 from a-leung/develop
- FEATURE: Add Flipper gem (#124)
Once sorted into categories:
Features
- Add Flipper gem (#124)
- Add rubocop gem (#125)
Fixes
- Optimize serializer performance (#132)
- Remove Spirit hands (#123)
and voila, instant release notes that are accurate, comprehensive, and pretty!
Conclusion
To have great release notes from git commit messages, requires a small
change where writing each commit message succinctly with FEATURE
or
FIX
in the message and following Chris Beams’ commit message
style. Using the $ git
log
command to extract out messages creates a nice summary of
messages that are perfect for release notes.
The small effort adds up over time and the pay off is big!