Keeping track of changes to a project makes it easier for everyone to clearly see what has changed, but manually curating a changelog often falls by the wayside. Today, we're releasing a new skill called Keep a Changelog that makes maintaining a changelog as easy as annotating a commit message or adding a label to an issue or pull request. It is based on the ideas in the keep a changelog project.

The Keep a Changelog skill automates the process of maintaining a changelog file for a repository. We have been using this skill for a long time on our open source repositories. This skill helped us to communicate changes to internal and external consumers of our software packages or services as they happen in our code base.

Adding changelog entries

The skill relies on issue and pull request labels as well as markers in your commit messages. We found that using labels on issues and special markers in our commit messages did not require any change in our daily workflow. We think it is really important that in order to introduce and effectively use a new form of automation, developers shouldn't be forced to change their routine!

GitHub Issue with a changelog label

Let's take a quick look at how the skill works with an example workflow:

  1. An issue was raised by a co-worker
  2. After initial triaging, the changelog:changed label was added to the issue
  3. When this issue was closed a few days later, an entry to the CHANGELOG.md was automatically added via this commit
  4. The issue is now included in the CHANGELOG.md

Similarly, adding [changelog:change] to a commit message will add an entry referencing the commit to the changelog.

Commit message with a changelog marker

More information of available labels and markers as well as other conventions this skills follows can be found on the skill page.

Closing a release in the changelog

When we decide to release one of our open source NPM packages or our services to production, we create a release tag in Git and ultimately a GitHub Release (this also happens through a skill but more on this in a later post).

Changelog entries added to a GitHub Release

The Keep a Changelog skill detects those release tags and GitHub releases and automatically closes the Unreleased section of the changelog. In this commit we released version 1.0.0 of the skill. And because we are using GitHub Releases, the skill automatically added the changelog to the GitHub Release.

Alternatively, you can use the chat command @atomist close changelog to close out a section in the changelog if GitHub Releases aren't used in your projects.

Try the skill on your own repositories from the Keep a Changelog page in our catalog today. We are looking forward to hearing your feedback about the way it works and how we can make it even better.