ChangeLog Overview

ChangeLog uses Git commit comments and tags from a local repository, combined with issue information from an associated remote repository, to build a change log.

Parameters are highly configurable, and Velocity is used to generate the output, enabling the user to modify presentation however they wish.

Alternatives

There are quite a few similar projects out there, and the preference would have been to use one that already exists. None of them quite do what was wanted, although in functionality terms Github-Changelog-Generator looked very good. Unfortunately, for our purposes it introduced a dependency on Ruby, for which we have no other purpose.

Github-Changelog-Generator also provides a useful list of similar projects.

Limitations

Currently only GitHub is supported as a source of issue information. This limitation is actually caused by GitPlus, which is used to manage the interaction with Git) (Contributions of other implementations would be very welcome)

Languages

ChangeLog is written in Kotlin, but published as a Java library. Kotlin is 100% interoperable with Java

Configuration and use

Instantiation

Using Guice

Include a ChangeLogModule instance in your injector and inject ChangeLog where required

Without Guice

ChangeLogFactory.getInstance()

Minimum Configuration

A minimum configuration requires a project name, the user name of the remote repo, and target project's parent directory:

changeLog
   .projectName('a-project-name')
   .remoteRepoUser('remote-username')
   .projectDirParent({parent directory of the target project})

API Keys

An API key is needed to access issue information and potentially to push the change log output to the wiki. An appropriate key should be located as described in the GitPlus documentation

Generating the output

Once configured:

changelog.generate()

There are many configuration options, but this minimum configuration will:

  • generate a change log based on tags (every tag is considered to be a version).
  • create a 'version' called 'current build' for any commits after the latest version (some refer to these as 'unreleased commits')
  • create a Markdown output, called 'markdown.md', placed in the root of the local copy of the associated wiki repository.
  • Push the change log update to the wiki (the local wiki repo must exist and be properly configured for Git push)

Sample Outputs

The links below all use the standard Velocity template - you can of course change that and use your own template by changing the templateName property

Projects

changelog