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 not from your Changelog).

That’s not bad in general (and it is much better than you don’t have 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 not guaranteed result!) to search repository and 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, those 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:’<li><a href=”http://github.com/danny-briskin/classifyIt/commit/%H”>view commit &bull;</a> %s</li> ‘ –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 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.

What if we forgot to tag a commit to mark a specific version? How can we figure out now, what has changed since version 1.0.0? Between 1.1.2 and 1.2.5? And why was it changed?

Let’s enforce proper commit messages

We can use Git hooks to prevent contributors making commits, violating some rules we want to see in commit message. For example, if we change 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 user to commit 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

will succeed.

In the same way, we can enforce users to add a type of change (from predefined list), business area and other useful information. In fact, all specifications exist and can be used. See Semantic Version or Conventional Commits.

There are only two drawbacks for git hooks:

1. Hooks are not saved in version control, so it is not easy to spread it to all project participants.
2. Hooks are not always cross-platformed. You need to use a high-level programming language to make it work cross-platform but you must have that language installed on every device where hooks are used.

On the other hand, there are systems with built-in (and highly customizable) hooks, like Bitbucket. A “must have” thing to turn on there is Require issue keys in commit messages and you can enjoy commits with a link to task number.

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. The idea of the application is to maintain previous version (that was already in changelog) and add all new commits (done in a Conventional way) as a release notes between previous and current versions. It makes tag for the updated version in Git and changes previous version to new one in configuration file(s) for the project. The application is customizable, using command line parameters and configuration files you can achieve a perfect changelog like this.

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.

[su_divider top=”no” size=”1″ margin=”20″]

Danny Briskin

QA Automation Manager
Danny has 25 years of working with software development, QA automation, Software Operations and Database/data Warehousing. He is a QE practice manager and Test Automation leader for QA consultants’ test automation solutions. With a master’s in Computer Science, Danny is also involved in research on developing QA Innovations and new technologies applied to artificial intelligence and machine learning.