Changelogger: Writing comittable changelogs

We all know, a good project needs a changelog. Either for other devs to inform them about breaking changes or for our users, who want to stay up to date about new features. Changelogs are incredebly useful, if done in a good manner. At our company we keep a changelog for our users. But writing them was a tedious and time-consuming task. I did some research and ended up writing a CLI tool helping us: Changelogger.

tl;dr
New CLI tool named 'Changelogger'. It creates for each change a separate file, which can be committed and on release day, it grabs all logs and add them to CHANGELOG.md.

The Problem

We use GitLab and like other projects we use Issues to manage every bug or feature. If something has changed, which needs to have a changelog entry we used to write the log message into the body of the issue.

This worked int the beginning, but now it became complicated. Either the programmer forgot to add a changelog or the reviewer merged the merge request (MR), but the changelog was missing. The MR had no information if a changelog is added or missing.

But the most annoying work were during a release. We need to manually copy all logs into a single file, organize them and then publish. If you manage like 3-5 issues, this is not a big deal, but our team grew and we fix more bugs, add more features and know we deal with like up to 50 issues.

We need help!

The Solution

We though about the problems, and few requirements were set:

• Adding a changelog should be easy
• The changelog needs to be visible within a MR
• Avoid merge conflicts

This first idea was, we add a CHANGELOG.md file and we write every log directly to the file. But this is not a smart idea, to be hornest. Because if many developer start adding new log, merge conflicts are happening pretty often. So I did some research.

Keep a Changelog

Quickly, I found Keep a Changelog. This is not a standard but a recommendation. Oliver Lacan wrote it and I think he did a great job. He describes a good format for a changelog and shows the advantages of keeping a good changelog.

The site is nice, but still not a solution to our problem.

GitLab

I found this documentation at GitLab about Changelog Entries. The engineers at GitLab had have the same problem and wrote a bash script, which simply creates a new YAML file for each log, which can be comittet.

This is a good start. But I wanted more.

Changelogger

I love open source, and I think writing changelogs need to be easier. So I started to put the idea into code and wrote "Changelogger". It's a CLI Tool for any project to add new logs.

You can either use Composer to install it as dependency to your project or install it globally. If you're not a PHP developer feel free to download the PHAR file, which is a PHP executable archive format.

Important: Please note, that the project is still in beta. Check the changelog for information about breaking changes. Also keep in mind, that breaking change may happen in minor versions until 1.0.0 is released (see SemVer).

Features

The idea of the tool is simple. Add a log, and during release grab all logs and add them to the Changelog.

• changelogger new: Create a new log entry. The tool asks for the type
• changelogger show: Show all unreleased changes
• changelogger release <tag>: Take all unreleased changes and add them to CHANGELOG.md
• changelogger clean: Fresh Start. Remove all unreleasd changes

Authors

At GitLab the added an author field. For GitLab-engineers the field is omitted, but if you are contributing to the open source project, you are allowed to add your name to take credits for the change (even if it's only a typo fix).

This is pretty neat and it encourages people to contribute, I think. So using the author flag changelogger new --author 'Peter' you can fill in your name.

Groups

This is still a feature in work, but we build a large software with many modules. To keep the changelog readable we divide the logs into sections for each module. You can add a config file to the root of your project and define the groups you need.

# .changelogger.json
{
  "groups": [
    "Module 1",
    "Module 2",
    "Module 3"
  ]
}

If groups are available the tool will also ask for a group.

Empty Logs

We though about empty logs as an option to add a log file to the merge request but only to indicate that this change does not need a log entry. So the reviewer can see, that this change is not meant to be listed in the changelog.

This also allows us to configure our CI Pipeline to check for the existance of a log file. So the programmer did not forget the changelog at all but rather state that s/he thinks that this change does not need an entry.

Internals

The tool is written in PHP using the Laravel Zero. However, like I mentioned about you can use the PHAR to run the tool directly. Only PHP 7.1+ is required as interpreter.

Each new log file is put into the directory ./changelogs/unreleased and is a basic YAML file.

What do you think?

I would like to know, do you keep a changelog and do you write them with passion or is a changelog more a waste of time?

What do you think about Changelogger? Could such a tool help you writing better changelogs?