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 the purpose and reasons that led to the change. Using a version control system (VCS) can greatly help in backtracking but its capabilities are very limited. In addition, VCS contributors are usually focused on making the needed changes rather than describing what was done. What’s more, work on a 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 a 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 is vital.
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).
While a Changelog is helpful, it still doesn’t provide the needed comprehensiveness such as “How this text document is related to the 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 to search the repository for that specific change with no guaranteed result. And when or if it is found, the commit message could be even more scarce, such as
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 •</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 such as dates, authors – things we need. What can go wrong? Those messages… Have you seen them before?
- 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.
will fail, while
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:
- Hooks are not saved in version control, so it is not easy to spread it to all project participants.
- 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 so 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.
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.