If you are tired of manually maintaining your changelog files, the following solution may help you as it helped me.
At Neoteric, we have quite a lot of services to maintain. Some time ago, we introduced proper versioning and releasing. That was a great step forward, but we were still missing an important piece. We wanted to have an easy way to know what was introduced (features & bug fixes) in each version. Appending information to a changelog file manually quickly became a tedious job, as our release cycles can be very short.
To overcome this, I came up with a solution of having the changelog file generated automatically out of Git commit messages. It consists of two parts. First is about adding a generated HTML file to a released Maven artifact, so it can be easily accessible in Maven artifacts repository (such as Nexus). The second part is about keeping an up-to-date changelog.md file in the project root folder.
This fit our Git-flow releasing cycle flawlessly (the whole process occurs in a release branch). I already described our cycle here. However, it shouldn’t be much of a hassle to adapt the solution to your preferred flow.
The core part of the solution is the maven-gitlog-plugin created by Daniel Flower. It’s a simple tool that gets most of the job done.
It generates changelog out of the Git commits. It can output to a text, markdown, HTML or even JSON file. It supports GitHub and JIRA issue trackers and its configuration is really easy.
All of the below XML snippets are a part of our ‘release’ Maven profile.
The baseline is to have the gitlog plugin set up and configured in pom.xml:
An important difference (in contrast to defaults) is the outputDirectory value. Instead of having the changelog generated in the target folder, we want it to appear in project root folder – to commit the files later on. Everything else is rather self-explanatory. To attach changelog.html to a released Maven artifact, we need to use builder-helper-maven-plugin:
Then in Nexus, we can easily navigate to the changelog:
See the sample HTML output .
Keeping an up-to-date changelog in your project folder requires the additional step of committing and pushing newly generated files:
Maven scm plugin needs the scm element specified. I had problems with defining Git addresses properly, but this Stack Overflow response did the trick:
That’s it. Your changelog always stays fresh. However, there is one catch from now on. You should pay attention to the quality of your commit messages (nice writing on that by Chris Beams here). But… you were already doing that, right?
