Keep track of your Software
While developing a project 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 deliverable is handover identifying 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 Changelog
The Changelog file has a log of changes to the project. It is a simple text file, structured, 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 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 site keepachangelog.com and follows the semantic versioning.
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 the
missing sections were intentionally left out because they contained no
notable changes.
As we can see, for the specified version, 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, the cleaning rules are, most of all, 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?
Actually, there are only 6 common types referred to in the keepachangelog.com site, and it seems to be enough, but you should adapt 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, 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 been removed.
Conclusion
Having and keeping a changelog is not hard, quite the opposite, but requires discipline. Discipline to follow the guidelines, having structured messages so a human can read the file. By 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 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 more easy J
