Skip to main content

Keeping a changelog

It is advised to keep a list of all notable changes that have been made in the source code of an application. By doing so, current and future contributors have a concise and clear overview of what has changed between different versions of the app.

The changelog is usually named CHANGELOG.md and written in markdown format. It should be easily accessible, therefore ideally be placed on the top level of the source code repository:

my-app
├── app
├── ...
├── CHANGELOG.md

Example changelog​

These are a couple of guidelines to keep in mind:

  • Add a small text on top to mention the type of versioning that is used (e.g. semantic)
  • Order the changelog entries chronologically with the latest changes on top
  • Group entries per type of change:
    • Added: new features
    • Changed: changes in existing features
    • Removed: removed features
    • Fixed: bug fixes
  • Add a date with each new version

An example is provided below, which can also be used as template for your applications:

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

Semantic versioning is used to denote different versions of this project.

## [Unreleased] - YYYY-MM-DD
### Added
- EntityTypeA: Report download

### Changed

### Removed

### Fixed
- EntityTypeB: Aspect ratio in SVG visualization

## [v0.1.0] - 2021-01-19
### Added
- Setup entity type structure with EntityTypeA and EntityTypeB
- EntityTypeA: MapView visualization
- EntityTypeB: SVG visualization

Semantic versioning​

Semantic versioning is commonly used to denote the different versions of an application. The convention that is used for the version number has format vX.Y.Z where:

  • X is the major: increments when a backwards incompatible change is introduced.
  • Y is the minor: increments when a new functionality is added, without breaking compatibility with older versions.
  • Z is the patch: increments when the code can drop-in-replace the previous code, or when documentation is added/changed.

Referencing to issue number​

In case you develop and maintain your application code in a source-code hosting facility which has a ticketing system (e.g. GitHub, GitLab, BitBucket etc.), the changelog will often also be visible in the interface. It is possible to refer to a specific ticket (issue number), which is very helpful to easily trace back to the historic moment of a specific change.

For example, in GitLab you can refer to the issue number using a "#" symbol:

- (#123) EntityTypeA: MapView visualization