Red Green Repeat Adventures of a Spec Driven Junkie

Writing Release Notes with git log

Relief of a Female Deity's Head

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:

$ git log --graph --pretty=format:'%s' --abbrev-commit --date=relative master..release

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 FEATUREor 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!