Better release notes for your git repository
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!!
Let’s see what we get with this format:
The release notes in this format:
- show the release versions and the associated dates
- show the pull requests that led to the release
- provide a link to the commit range. This is just an easy git compare path based on tags; e.g. I can get the commits that went into v3.18.5, which are the commits that happened after the previous release - v3.18.3, by navigating to https://github.com/TestStack/TestStack.BDDfy/compare/v3.18.3…v3.18.5
- 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!
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.
Hope this helps.
###v3.18.5 - 2014-02-03
- #46 - tidies up the layout of the summary pane in the HTML report
###v3.18.3 - 2014-01-24
- #42 - fixes a bug that caused html report to fail when there is a BDDfy test without an associated story
###v3.18.2 - 2014-01-13
- #40 - reduces memory footprint by disposing unnecessary objects in StoryCache
- to reduce the memory foot print,
ExecutionStepare nulled out before persisting the story in
StoryCacheas 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.
###v3.18.0 - 2014-01-02
- #38 - adds a configuration point to stop execution pipeline on a failing test
###v3.17.1 - 2013-11-04
- #32 - adds support for async steps
###v3.16.14 - 2013-08-05
- #30 - cleans up samples and adds a simple BDDfy Rocks one
- #28 - adds nuget tags
- #27 - updates nuspec files with the latest license (MIT) & project url
- #26 - removes nuget readme content file
- #24 - removes some text from readme & pointed to the new docos website
- #23 - changes the license to MIT
- #25 - changes the html report link & fixes the custom scripts
- #22 - renames custom script names and fixes the report link - Fixes issue #18