Skip to content

Changelog

Used in the playbook Quality and release.

Download changelog.md — the source, as in the repository.

How to use

The template's own instructions:

UASK Engineering Hub template · changelog 0.1.0 · playbook quality.quality-release (R4, R10) · CC BY 4.0 Copy to the project root as CHANGELOG.md. Format: Keep a Changelog 1.1.0; versions: SemVer 2.0.0 (Hub item config.semantic-versioning).

  • Add a line under Unreleased in the same pull request as the change, when users will notice it.
  • At release, rename Unreleased to the version and date, and start a new empty Unreleased.
  • Write for users: what changed for them and what they must do. Not a list of commits.
  • Categories, in this order, only those that have entries: Added, Changed, Deprecated, Removed, Fixed, Security.
  • Mark breaking changes with "BREAKING:" and give upgrade steps for every MAJOR release.
  • Dates are YYYY-MM-DD. Newest version first. Never rewrite a released entry; correct it in a later one. Delete these comments in the copy.

Fields

Front-matter fields and sections of the document the template creates. A section marked Optional in the template may be deleted from a copy; every other field and section stays (tools/check_artifacts.py checks this for the kinds it knows).

Field or sectionWhereRequired
[Unreleased]sectionrequired
[1.0.0] - 2026-01-01sectionrequired

Example

A filled-in copy for an invented product, templates/examples/changelog.md, in the Hub repository.It shows the level of detail to aim for, not text to reuse.

example-changelog.md
# Changelog
All notable changes to this project are documented in this file.
The format is based on [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/), and this project
adheres to [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
### Added
- Notes can be exported as a zip of Markdown files from the settings screen.
## [1.0.0] - 2026-06-01
### Added
- First release: write notes offline, merge them with a Git host, export everything as plain files.
[Unreleased]: https://example.org/example-org/fieldnotes/compare/v1.0.0...HEAD
[1.0.0]: https://example.org/example-org/fieldnotes/releases/tag/v1.0.0

Completion checks

A copy is complete when:

  • every required field and section above is present, in the same order, and no bracketed placeholder is left;
  • the template's comments are deleted from the copy;
  • the exit criteria of its stage of the playbook Quality and release are met;
  • the owner has approved it, where the playbook asks for approval. Only the owner sets approved.

Source

templates/changelog.md, as in the repository. Placeholders are in square brackets; comments carry the instructions.

changelog.md
<!--
UASK Engineering Hub template · changelog 0.1.0 · playbook quality.quality-release (R4, R10) · CC BY 4.0
Copy to the project root as CHANGELOG.md. Format: Keep a Changelog 1.1.0; versions: SemVer 2.0.0
(Hub item config.semantic-versioning).
- Add a line under Unreleased in the same pull request as the change, when users will notice it.
- At release, rename Unreleased to the version and date, and start a new empty Unreleased.
- Write for users: what changed for them and what they must do. Not a list of commits.
- Categories, in this order, only those that have entries: Added, Changed, Deprecated, Removed, Fixed, Security.
- Mark breaking changes with "BREAKING:" and give upgrade steps for every MAJOR release.
- Dates are YYYY-MM-DD. Newest version first. Never rewrite a released entry; correct it in a later one.
Delete these comments in the copy.
-->
# Changelog
All notable changes to this project are documented in this file.
The format is based on [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/), and this project
adheres to [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
## [1.0.0] - 2026-01-01
### Added
- First release: [what users get, in one or two lines].
[Unreleased]: https://example.org/OWNER/REPO/compare/v1.0.0...HEAD
[1.0.0]: https://example.org/OWNER/REPO/releases/tag/v1.0.0