Maintenance of system changes and changelog automation

The Issue

In a project with a long history, it’s often good to have all information about changes stored. Not only the date, author and content of the change but also a motivation that led to the change. Using a version control system (VCS) can greatly help in backtracking but its capabilities are very scarce. In addition, VCS contributors are usually concentrated on contributing rather than description of what was done. What’s more, work on the project can be done in parallel, by several people, not in a “logical” sequence (from business perspective). For example, a customer login form could be implemented much earlier than customer registration form. And if you must support several versions at the same time, questions like “What was changed in version X?” and “Why that change was (or was not) included in version Y?” can become a nightmare. In that case, a proper tracking of changes could be vital in the project.

Changelog

A changelog is a file, where changes that were made since previous version, are described. A typical changelog looks like:

## 1.2.0 (2021-08-04) Feature
**registration** new registration form

## 1.1.1 (2021-08-03) Bug Fixes
**login** correct minor typos in code

## 1.1.0 (2021-08-03) Feature
**login** login form was added

## 1.0.0 (2021-08-01) Initial release

In other words, a changelog is a composition of Release Notes (or you can pick a release note from your changelog).

That’s not bad in general (and it is much better than not having any changelog!). But it begs questions: “How this text document is related to VCS or task management system? How to find contents of the change mentioned in version 1.1.0?” A support engineer must spend a lot of time (with no guaranteed result!) to search the repository for that specific change. And when/if it is found, the commit message could be even more scarce, like:

fix bug

When the project grows bigger, it will take even more resources to maintain the changelog. And yes, this is manual work, which needs to be done by someone.

Git log becomes a changelog! And failed…

Well, as you know, developers ought to write some commit messages anyway. Let’s not do the same work twice! Can we convert a set of messages into a changelog? Easily, with the power of git log command:

# like this
git log --pretty="- %s"

# or like this
git log --pretty=format:'view commit • %s ' --reverse

# even between versions (tags) if you have it in the repo
git log v2.0.0...v3.1.0 --pretty="- %s"

Each of those commands will bring us a file that looks like a changelog. At first sight, it will consist of the first lines of commit messages (yes, we can play with --pretty and --format parameters to get the full message), dates, authors – things we need. What can go wrong? Those messages… Have you seen it?

Bug fix
Code was fixed
created variable instead of parameter
new attempt for the latest Jira task

Will it help us in our investigations? Of course not.

Let’s enforce proper commit messages

We can use Git hooks to prevent contributors from making commits that violate some rules we want to see in commit messages. For example, if we change the commit-msg hook to something like:

#!/usr/bin/env python3
import sys
import re

with open(sys.argv[1]) as file:
    content = file.read()
    if (not re.match(r'[JIRA-d+] - .+', content)):
        raise NameError("Please add Jira task number in commit message! {}".format(content))

it will prevent users from committing without a “link” to the task that commit is related to. I.e.

git commit -m"Test" MyFile.java

will fail, while:

git commit -m"[JIRA-123] - Test" MyFile.java

Let’s automate changelog

Having forced contributors to make intelligible commit messages, let’s automate changelog creation. Let me introduce one of such applications: Standard Version. It uses Node.js as an engine, so it must be installed prior to use. Even though it was designed for Angular, it can be easily used in most software projects that have Git as a VCS.

Summary

Having a proper changelog can greatly boost your system maintainability. It could ease not only backtracking but enables a clear view of system development through time and links together version control, task management, and support procedures.