Better release notes for your git repository

Feb 8, 2014

In the last post I mentioned that I struggle with release note duplication: I want a release notes file in my repo, release notes in my NuGet package and then there is GitHub releases with their own notes, and I hate duplicating release notes all over the place. There was an entry in my wish list asking GitHub to provide a way to automatically update the release-notes.md file on creating a release entry; but I changed my mind. There is a better way: a good release-notes file!!

I just created a new release-notes.md file for BDDfy. A few release entries are copied at the end of the post for your reference.

highlight the in-development work on the top. This also makes it very easy to create new releases: basically every time you merge in a PR you add an entry to ‘In development’ section and upon releasing just tag your release, change the Commits range to use the newly created tag, create a release title with date, and you’re done.

classify the changes so users can differentiate the fixed bugs, new features and improvements easily

includes breaking changes next to release changes. Before I loved having a breaking-changes file on the root of the repo so the users know how to deal with potential breaking changes (a sample from Seleno codebase). Although the release version is included in the breaking changes file, it’s disconnected from what actually happened on the release. Using this format the breaking changes are right next to all other changes that go into the release so you can see what changes led to the breaking change and have a lot more context around it.

Another benefit of creating a release-notes file is that it works with all git hosts (e.g. Stash, BitBucket, CodePlex etc) and not just GitHub.

Obviously you could get all of the above benefits from GitHub releases.

No need for GitHub releases

A while back I asked on Twitter why people use GitHub releases and the only convincing answer I got was that it allows users to see the releases and commits that goes into them easily. Well, this format does that - so I don’t need GitHub releases anymore!

Here are a few benefits of getting rid of GitHub releases and completely replacing them with release-notes:

DRY: duplicating release notes in two places involves more work and is error prone., which I can avoid now.

No useless downloads: creating a GitHub release for a library/framework provides useless download buttons that give you the repo! If you want the repo you should clone it and to download libraries devs should use package managers (e.g. NuGet, npm, gems), and no I don’t want to put binaries on GitHub release. That’s more pointless work. And please don’t give me “but NuGet went down!!” argument. That doesn’t work with me.

Can see the releases locally: your release notes are in the repo which means they are available on your local clone and when you’re offline and you don’t need to go to GitHub to see what got changed in a particular release. And it’s markdown so you can see it formatted very nicely. Also if you ever decide to use a different host you’re out of luck with GitHub releases (at least to the best of my knowledge); but with release-notes the releases become an integrated part of your repo and you can take them with you wherever you go.

A handy feature of GitHub you’ll be missing out is the issue and pull request lookup. GitHub has a very handy lookup mechanism when you put a hash (#) on comments and messages that provides you with a list of existing issues and pull requests that also filters down as you type part of their message. Also they turn into links so you can just click on an issue or pull request number to navigate to it. When you create your release-notes you have to write this yourself: no issue and pull request autocomplete lookup and if you want links you have to create them yourself. Honestly while this is a loss of a handy feature, I can easily live without it.

To get the best of both worlds it would be ideal if GitHub Release worked as a glorified GUI over the release-notes file. I don’t understand why GitHub decided readme and license files should be part of the repository but releases have to live outside!

Conclusion

In this post I showed you how I just stopped using GitHub releases and replaced it with a proper release-notes file, and I highlighted some of the benefits of this approach.

One thing I didn’t talk about is NuGet release notes. I think I will just create a link to a release entry on release-notes file for that - something like this.

Credit where it’s due: I didn’t come up with this format. This is borrowed from Yeoman’s generator release. Next I will try to automate parts of this process using this package.

Improvements

Breaking Changes

to reduce the memory foot print, TestObject on Story class and StepAction on ExecutionStep are nulled out before persisting the story in StoryCache as these two properties leave a lot of dangling objects in memory (see #39 for more details) and they’re not used in BatchProcessors. Not sure why you would, but if you were using these properties from your tests they’ll be null after the test is executed.