About the CHANGELOG file

Version 1.0

What it is, best practices, versioning and an example

Version control table

Version	Date	Comments
0.1	18/08/2023	Initial draft
1.0	12/09/2023	Published Document

What is a CHANGELOG?

A CHANGELOG (change log) is a structured record that documents changes made to a digital service over time. It acts as a chronological logbook, detailing modifications, enhancements, bug fixes, and iterations that occur during the digital service’s development lifecycle. The CHANGELOG serves as a communication tool between teams of developers, testers, and end-users, providing transparency and accountability for alterations made to the digital service.

Why is a CHANGELOG Important?

Tracking Progress: A CHANGELOG allows teams to monitor the evolution of a digital service. By documenting each change, from minor bug fixes to major feature enhancements, everyone involved can understand the project’s development trajectory.

Bug Identification and Resolution: CHANGELOGs help in identifying and addressing bugs and issues that arise during development. By noting which problems were fixed in each version, teams can quickly pinpoint and address recurring or persistent issues.

Enhancing Collaboration: Developers, testers, and other stakeholders can collaborate more effectively when using a CHANGELOG. It clarifies what has been changed, and helps in discussions and decisions about the digital service’s direction.

User Transparency: End-users benefit from CHANGELOGs as they gain insight into the changes that impact their experience. Clear communication of updates helps manage user expectations and reduces confusion.

Release Notes: CHANGELOGs often serve as the basis for creating release notes. These notes inform users about the changes in a new version, making it easier for them to understand the updates and adapt to any modifications.

Version Control: Maintaining a CHANGELOG complements version control systems, enabling better organization and management of different software versions. This ensures that development is coordinated and prevents version conflicts.

Historical Reference: CHANGELOGs act as historical references for digital services. They provide a comprehensive overview of the development journey, aiding future developers who may need to understand past decisions and changes.

Guidelines for a Well-Structured CHANGELOG

Guiding Principles:

The target audience of a CHANGELOG is humans, not machines: Write your CHANGELOG with readability in mind. Use clear language and concise descriptions that non-technical stakeholders can understand. Use markdown language.

An entry for every single version: Each version, no matter how small, should have its own entry in the CHANGELOG. This helps users understand when updates were made and what they encompass.

Group the same types of changes: Categorize changes into meaningful groups, such as “Added,” “Changed,” “Deprecated,” “Removed,” “Fixed,” and “Security.” This grouping enhances clarity and aids quick scanning.

Link the Versions and sections: Provide unique identifiers for versions and sections, making it easy to link directly to specific entries. This supports effective referencing and sharing.

The latest version should be on top: Present the most recent changes at the top of the CHANGELOG. This aligns with how users tend to focus on the latest developments.

Display the release date of each version: Include the release date of each version to give users a timeline of when changes were introduced.

Types of Changes:

Use the following standardized categories to label changes:

Added: Use this for introducing new features or functionalities.

Changed: Employ this category for modifications to existing functionality, improvements, or updates.

Deprecated: Label features that are planned for removal in future releases. Provide details on alternatives, if applicable.

Removed: State features that have been permanently removed from the software.

Fixed: Indicate bug fixes and solutions for issues that have been resolved.

Security: Use this category to communicate vulnerability fixes or security enhancements.

Naming the CHANGELOG

Name the file “CHANGELOG.md” to make sure teams can effortlessly locate significant updates without unnecessary confusion.

Versioning

Effective versioning enhances clarity and consistency in your CHANGELOG.

Semantic Versioning (SemVer): We are following the Semantic Versioning for clear version communication. Semantic Versioning consists of three parts: MAJOR.MINOR.PATCH.

MAJOR: Increase when making incompatible changes that require users to adapt or changes in functionality. For example, changing the database structure in a way that existing data cannot be seamlessly migrated.

MINOR: Increase for backward-compatible additions or enhancements. For instance, introducing new features that do not disrupt existing functionality.

PATCH: Increase for backwards-compatible bug fixes. Fixing a critical security vulnerability or resolving issues that affect user experience are examples of patch-level changes.

Version Naming: Based on the type of changes, we’ve set up GitHub to automatically provide a version of your release.

Manual Bumping (using merge commit message): “Bumping” is the process of deliberately increasing the version number. Any commit message that includes certain keywords such as #major, #minor, #patch, or #none will trigger the respective version bump during the merging process. The highest-ranking keyword present in the commit message determines the type of version bump. If the commit message includes “#none”, it prevents any version bumping, even if there’s a default rule for bumping (DEFAULT_BUMP).

CHANGELOG Entry for Each Version: Maintain consistency by ensuring there’s an entry for every version in your CHANGELOG. Even if the changes are minor, they help teams understand the progression of the digital service. For example, even a small bug fix release like “0.0.3” should have an entry.

Release Date: Display the release date of each version alongside its entry. This chronological information aids in tracking the evolution of the digital service. For instance, “[0.0.3] – 2023-08-15” provides a clear timeline.

Here’s a CHANGELOG example

## [1.0.0] – 2023-08-17
### Added
– Specific feature 1
– Specific feature 2

### Fixed
– Fixed a specific bug that had caused a specific problem

## [0.0.3] – 2023-08-15
### Changed
– information about what changed in this version

### Removed
– Remove text from section “xxxxx” because of reasons

## [0.0.2] – 2023-08-10
### Added
– Explanation of what was added.

## [0.0.1] – 2023-08-05
### Added
– Other information.
– CNAME information.
– README information

[1.0.0] https://gov-cy.github.io/xxx/v1.0.0
[0.0.3] https://gov-cy.github.io/xxx/v0.0.3
[0.0.2] https://gov-cy.github.io/xxx/v0.0.2
[0.0.1] https://gov-cy.github.io/xxx/v0.0.1