Changelogs are simple text files which help keep track of changes to documents which don’t support tracked changes or versioning, such as QGIS projects.
To help other people using a product, include a simple changelog file which provides a chronological list of important changes to a file. This can contain more detail than you would typically add to a Trello card. When a new person starts updating or editing a product, they can read the changelog to understand the changes and decisions that have already been made.
This guidance is adapted from the changelog standard at keepachangelog.com, which goes into more detail.
Guiding Principles
- Changelogs are for humans, not machines.
- There should be an entry for every single version (set of changes)
- The same types of changes should be grouped.
- The latest version comes first.
- The release date of each version is displayed.
- The name of the person making the edits is displayed.
Semantic Versioning
Semantic versioning provides a standard way to assign version numbers to software releases, allowing developers and users to understand the significance of each update and its impact on backward compatibility. Updates are tracked with three numbers, with each place signifying how “big” of an update it was: major.minor.patch. For example, if someone were to fix a spelling mistake in a 1.0.0 product, it would bump the version up to 1.0.1. But if someone took a map and added an entirely new layer, it would get bumped up to 1.1.0.
- Major version for significant changes or milestone – e.g. publication.
- Minor version for adding new functionality, datasets, etc.
- Patch version for small fixes/edits Compared with software development, this is a bit subjective when applied to designed products but is a good structure to use as a guide
Types of Changes
Changes should always fall under one of the following types:
- Added for new features.
- Changed for changes in existing functionality.
- Removed for now removed features.
- Fixed for any bug fixes.
- Published for any approved publications of the product
Recommended Usage
When creating a new file, include a changelog called _changelog.md. The leading underscore ensures the file will appear at the top of the folder when sorting alphabetically. The .md file extension refers to Markdown formatting.
Change Entry Headers
A single # denotes a top-level header, which is where you’ll include the version number, the date in yyyy-MM-dd format, and the SIMS member responsible for the changes. For example:
# [0.0.1] - 2023-05-01 – Alexei SchwabAlways start versioning at [0.0.1] and prepend new updates above the previous one.
Insert Update Information
Two #‘s denote a header nested inside the preceding entry header. To expand on the example above, here’s what would be included under the [0.0.1] header:
# [0.0.1] - 2023-05-01 – Alexei Schwab
## Added
- Initiated QGIS project for SIMS task P01 Sudan basemap
- Added core data (roads, admin boundaries, satellite imagery)
- Added basic SIMS styling to data Reserve Major Updates for Published Changes
When the SIMS Remote Coordinator sends out the final product back to the field and it is approved and circulated, consider that a major point release. If the field comes back with substantive changes requested to the product, start logging the minor and patch updates from there, again waiting until the next revision is accepted by the field before bumping the version up a whole (major) number again.
Sample Changelog
Here’s what a complete changelog may look like:
# [1.0.0] - 2023-05-05 – Jonathan Garro
## Published
- Map approved by SIMS Co. and sent to field team.
# [0.1.2] - 2023-05-03 – Paul Knight
## Fixed
- Moved roads layer to geopackage database in project folder rather than local file and relinked layer datasource.
# [0.1.1] - 2023-05-02 – Alexei Schwab
## Added
- Newer roads layer from HDX
- Overview map
## Changed
- Increased size of labels for better readability
- Changed colour of major roads to yellow to stand out more
## Removed
- Satellite imagery layer, following feedback from SIMS Co
# [0.0.1] - 2023-05-01 – Alexei Schwab
## Added
- Initiated QGIS project for SIMS task P01 Sudan basemap
- Added core data (roads, admin boundaries, satellite imagery)
- Added basic SIMS styling to data