Creating beautiful release notes with git, gradle and markdown

During the last days I asked myself how to generated releases notes from information that are available in commit  / tag messages from git.

The decisions

My first approach was to create the list of changes directly from the commit messages, but this approach has multiple drawbacks.

  • The commit messages must be written very disciplined
  • An marker is required to collect messages that belongs to a release (A usual tag would be sufficient for that)
  • The content of the commit messages must follow conventions, so that featuresbugfixes and changes could be collected and displayed in one block

So I go for annotated tags, which must provide a message with a tag. Creating them is fairly easy with git

Sidenote:
This kind of tags has a nice addition, it allows to check which commits belongs a specific tag

The next decision was about the markup language that should be used for the messages. Because I’m a fan of markdown, I decided to go for that. This will lead to human readable messages and a well known and working parsing.

Important hint
Git interprets # usually as the start of a comment. The annotated tags must be created with the option –cleanup=verbatim to suppress this feature if you would like to use more than the first and second header.

With this decisions I started to implement a small example in gradle, which creates the release notes during the build process. I the next section I show you the required code

Implementation

Prerequisites

Because I want to have also a beautiful version of the release notes I decided to convert the markdown directly to a html page. For doing this I use PegDown as Markdown processor and twitter bootstrap with bootswatch themes for styling the output.

Initial build script

 Implementing the logic

We start with the task the controls the process of generating the release notes

The process is really simple.

  • First we clean up old artifacts of a markdown file (line 2 and 3). After this we created the section Versions and load the available tags (lines 5 till 10) and put everything into a separated list.
  • Then we create information about the Release Notes and add a header for each tag followed by the message belonging to this tag (lines 12 till 18).
  • As a last step we parse the markdown file and create a html page by passing by the parsed values to a template.

As you see three more components are required

  1. the readTags method
  2. the readTagMessage method
  3. a template for the html page

readTags

This method calls

and returns a reversed ordered list of tags

 readTagMessage

This method uses

to retrieve the message that was provided for this tag.

 releaseNotes.tpl

This template contains three properties application, releaseNotes and versions. Application is substituted with your applications name and used in the title. releaseNotes contains the converted release notes. And finally versions represents

As already stated in the prerequisites twitter bootstrap and a theme from bootswatch is applied to beautify the code.

Final

After putting everything together we can create a annoated tag and call simply

and gradle will read all the messages and tags and create two files

  • releaseNotes.md and
  • releaseNotes.html (Example - Thanks to a colleague of mine for his thoughts on layout and design for this version)

Conclusion

With this simple build script and a little bit conventions we can create release notes from our repository information. Additionally we don’t have to maintain multiple places of release notes, because everything is directly stored in the repository.

By using Markdown we have a simple markup and human readable markup language that allows us to create beautiful release notes for our web applications. It’s possible to parse the markdown information directly to a html page, as I did in this example, but you can also provide the simple markdown file and parse it on the client side or at delivery time on your server.

As usual the complete code is available on github https://github.com/coders-kitchen/tut-releaseNotesFromTags

Leave a Reply