I’ve been using Atlassians JIRA bug tracking tool and its really great, I like using it and it generally makes my life easier. However, one area in which I wanted a bit of extra flexibility was in producing release notes or Changelogs.
The way in which my colleagues and I operate is that every development task no matter how small or large gets raised as an issue in JIRA and pushed through a standard workflow involving everything from quality assessment of the content of the issue itself to development to code review to testing and finally release. As every development task is rasied in JIRA it means that every possible change within one of our software products is documented in JIRA as well as recording the release version for each issue.
As all this information is recorded in one place pulling a changelog out of JIRA should be easy and it is – out-of-the-box JIRA provides release notes for a given version directly from the “Change Log” link within a project overview. Instructions for this can be found here: JIRA – Browsing a Project’s Change Log. Whilst this is great to read as a summary what if you want to format this is a way that suits your software? For example, to create a plain text change log that goes into your build source or as HTML in the form of a user navigable page within your software product? JIRA offers a “Release Notes” view that generates the change log as some basic HTML but it doesnt give you any customisation.
Welcome, JIRAChangelogBuilder – this is a Java command line utility that allows you to connect to a JIRA instance and generate a change log in whatever format you wish. The tool connects to your JIRA instance, gets all the relevant information and formats the data using a user defined mustache template. You can write mustache templates to produce HTML, XML, a plain text file, or anything else that you can represent using a text-based template.
The idea with this tool is that it can be easily hooked in as a step of continuous integration, as a given release is created by a CI tool such as Jenkins or Bamboo the release notes and generated automatically and included. No more trawling through JIRA or through VCS commit messages to figure out the exact changes that went into this build. Using the mustache templates you can generate the changelog in whatever format suits you.
Another pain-point of manually creating release notes is translating the often techy wording that a developer has used to describe a change into something that the client can actually unserstand. For this we I have introduced an addition field in JIRA called “Changelog Description”. This field is specifically for a client facing description of the change and has been made mandatory using the excellent JIRA Suite Utilities plugin once development is complete and the issue is ready for build. The JIRAChangelogBuilder can be given the name of any custom field to use to pull release notes from. (It’s always worth sanity checking your release notes though especially if they’re available for public consumption!)
Various customisation options in the JIRAChangelogBuilder allow you to specify some JQL in order to filter the the appropriate issues for the release you’re targeting; specify one or more templates to use (yup, if you want to produce multiple formats of a change log then that can be done in a single call. I use it to produce an HTML based “pretty” change log and a plain text version); and cache previous change logs for past releases as a performance gain.
You can hook it into continuous integration tools so that as a build is created for release the change log gets generated and added where required. This really simplifies the pain-staking process of looking through JIRA or version control commit messages to ensure you’ve covered everything – if everything is in JIRA and the changlog uses JIRA its all good to be created automatically.
The tool is written entirely in Java and makes use of the JIRA REST API via the Atlassian JIRA REST Java Client which is very easy to use and provides a very comprehensive API. I’ve released the source under the MIT licence so feel free to with it as you wish!
Obviously this is not a replacement for a big media release detailing all the cool new features and fixes you’ve incorporated into a product but as a basic list of changes it serves a great purpose and takes no effort to create.
Go and take a look for yourself and find full instruction on my github at https://github.com/mleonard87/JIRAChangelogBuilder.