If you are tired of maintaining your changelog files manually, following solution may help you as it helped me.

At my current company 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 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). Second part is about keeping up-to-date changelog.md file in the project root folder.

This fit our git-flow releasing cycle flawlessly (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 preffered flow.

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.

Baseline is to have the gitlog plugin set up and configured in pom.xml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

    <plugin>
        <groupId>com.github.danielflower.mavenplugins</groupId>
        <artifactId>gitlog-maven-plugin</artifactId>
        <configuration>
            <fullGitMessage>true</fullGitMessage>
            <excludeCommiters>
                <commiter>jenkins</commiter>
            </excludeCommiters>
            <dateFormat>yyyy-MM-dd</dateFormat>
            <markdownChangeLogFilename>CHANGELOG.md</markdownChangeLogFilename>
            <generateMarkdownChangeLog>true</generateMarkdownChangeLog>
            <generateJSONChangeLog>false</generateJSONChangeLog>
            <generatePlainTextChangeLog>false</generatePlainTextChangeLog>
            <outputDirectory>${project.basedir}</outputDirectory>
        </configuration>
        <executions>
            <execution>
                <goals>
                    <goal>generate</goal>
                </goals>
            </execution>
        </executions>
    </plugin>

Important difference (in contrast to defaults) is outputDirectory value. Instead of having 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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

    <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>build-helper-maven-plugin</artifactId>
        <executions>
            <execution>
                <id>attach-artifacts</id>
                <phase>package</phase>
                <goals>
                    <goal>attach-artifact</goal>
                </goals>
                <configuration>
                    <artifacts>
                        <artifact>
                            <file>changelog.html</file>
                            <type>html</type>
                            <classifier>changelog</classifier>
                        </artifact>
                    </artifacts>
                </configuration>
            </execution>
        </executions>
    </plugin>

Then in Nexus we can easily navigate to the changelog:

nexus

Sample html output is available here.

Keeping up-to-date changelog in your project folder requires additional step of commiting and pushing newly generated files:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-scm-plugin</artifactId>
        <executions>
            <execution>
                <id>add-changelog-to-git</id>
                <phase>package</phase>
                <goals>
                    <goal>add</goal>
                    <goal>checkin</goal>
                </goals>
                <configuration>
                    <basedir>./</basedir>
                    <includes>CHANGELOG.md, changelog.html</includes>
                    <message>Add changelog</message>
                    <pushChanges>true</pushChanges>
                </configuration>
            </execution>
        </executions>
    </plugin>

Maven scm plugin needs scm element specified. I had problems with defining Git addresses properly, but this Stack Overflow response did the trick:

1
2
3
4
5

    <scm>
        <url>https://github.com/XXX/YYY</url>
        <connection>scm:git:ssh://git@github.com/XXX/YYY.git</connection>
        <developerConnection>scm:git:ssh://git@github.com/XXX/YYY.git</developerConnection>
    </scm>

That’s it. Your changelog always stay fresh. However, there is one catch from now on. You should pay attention to quality of your commit messages (nice writing on that by Chris Beams here). But… you was already doing that, right?