Keep track of your Software (2/2)

While developing a project, it is not uncommon that the project is divided into several stages. Using Scrum terminology, the project has several sprints in which some predetermined features are delivered, and at the end of the sprint one of these deliverables is the handover, helping to identify what was done within the sprint.

Although the above is applied to the Scrum framework, the principle is common to every software project, regardless of the amount of work done.

It is considered a best practice in software development that each artifact delivered is followed by a document that specifies the changes that were made. In some methods such as Release Management, it is required that this document is delivered with the project.

In almost all practices, this document is called CHANGELOG, and in some Git host providers (such as Gitlab), you can add a CHANGELOG template to aid the fulfilment.

What is a Changelog

The Changelog file has a log of changes to the project. It is a simple and structured text file, and reflects the changes straight to the point. It is NOT a trash bin to dump information; it is NOT a file where you leave the history of the git. It is a useful file that we can consult at any time and check what was done.

Although there is no ISO standard or RFC document that specifies the structure of the Changelog, the industry follows a format suggested by the website keepachangelog.com and uses the semantic versioning.

1. Changelog Structure

The Changelog should be very simple, human-readable, and commonly split into three sections:

• Header
• Unreleased
• Released

With this structure, the file intends to be analyzed quickly and get the most useful information fast.

Header

This section is straightforward and usually has information for the reader about the file’s intention and some contact information, although it is not mandatory.

Some Changelogs have minimal information such as:

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog] (https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

The structure follows markdown language to appear formatted in git hosts.

Unreleased

The “Unreleased” section should be the top section (after the “Header”) and reflects the work that was done but is not published yet.

An example:

## [Unreleased]

### Fixed

GLB-1982 — Fixed typo in the Web API call.

While delivering features, fixing bugs, etc., this section will increase and keep track of the work.

When a new release is made, all items in this section become a new version of the “Released” area.

Released

This section reflects the history of the project, what was done when it was done. Reflects all the changes that were made in each version.

An example (from the keepachangelog.com site):

## [0.0.4] — 2014–08–09

### Added

• Better explanation of the difference between the file (“CHANGELOG”) and its function “the change log”.

### Changed

• Refer to a “change log” instead of a “CHANGELOG” throughout the site to differentiate between the file and the purpose of the file — the logging of changes.

### Removed

• Remove empty sections from CHANGELOG; they occupy too much space and create too much noise in the file. People will have to assume that then missing sections were intentionally left out because they contained no notable changes.

As we can see for the specified version, this was what was done.

Guidelines for clean “Released” sections

Keeping useful “Released” sections requires discipline and should follow these guidelines:

• The latest version comes first. Each section should have the version and release date.
• The date should follow ISO 8601.
• Consider following Semantic Versioning.
• There should be an entry for every single version.
• Group changes by their type.
• Each change should be linkable to a work item.

Actually, most of all the cleaning rules are common sense. I keep it simple; we can keep a human-readable Changelog.

Changes Types

Like I mention before, we should group our changes by their type to have a clean section. So, which change types do we have?

There are only 6 common types referred to in the keepachangelog.com website that seem to be enough, but you should adapt it to your needs.

The change types are:

Added: for new features.

Changed: for changes in existing functionality.

Deprecated: for soon-to-be removed features.

Removed: for now, removed parts.

Fixed: for any bug fixes.

Security: in case of vulnerabilities.

src: keepachangelog.com

As we can see, these types should cover all needs. The most cautious type is the “Removed” type, since it may imply that by following Semantic Version that could be a breaking change, and we should consider increasing the Major version. The guideline that features should become deprecated before being removed.

Conclusion

Having and keeping a changelog is not hard, quite the opposite, but requires discipline. Discipline to follow the guidelines and having structured messages so a human can read the file. Keeping a clean changelog is a powerful tool of the project and in Release Management.

Although only a small set of the team should be able to fill the Changelog, all sections should be aware of the guidelines to edit the file if needed.

To simplify the changelog messages, the software development team may change how they write the commit messages to adopt “smart commits.” It is not recommended to dump git diff logs in the changelogs. However, if the team uses “smart commits,” the work of the guy that fills the change record becomes easier .😊

Nuno Cancelo
Polarising’s Microsoft Practice Lead