Skip to main content

ADR-0002: Standardized changelog and release documentation in A2C

  • Status: Accepted
  • Date: 2026-06-12
  • Deciders: Michel Gillet

Context​

A2C-governed repositories need a consistent, human-readable record of what changed in each released version. Git commit history alone is too granular and noisy for consumers, release planning, and adoption decisions.

Without an explicit standard, projects omit changelogs, mix commit dumps with release notes, or use incompatible formats that block semi-automated release workflows.

Decision​

Every A2C-governed software repository must maintain a root-level CHANGELOG.md file.

Standards​

Intent​

  • Provide a curated, human-readable history of notable changes per released version
  • Separate internal commit history from release-level notes
  • Support automated or semi-automated release workflows that rely on semver and changelog entries

When to update​

Update CHANGELOG.md when changes are user-visible or release-relevant:

  • features, fixes, breaking changes, deprecations, removals, security fixes

Maintain an ## [Unreleased] section on active development branches. Curate entries as work lands; finalize into a version heading at release.

Do not require changelog entries for minor internal refactors, non-user-visible tooling tweaks, or trivial documentation fixes that do not affect releases.

Required structure​

Aligned with Keep a Changelog:

  • ## [Unreleased] at the top (when using unreleased workflow)
  • Categorized subsections: ### Added, ### Changed, ### Deprecated, ### Removed, ### Fixed, ### Security (use only sections that apply)
  • One heading per release: ## [X.Y.Z] - YYYY-MM-DD
  • Optional compare/tag footer links when the project uses them

Relationship with ADRs​

ArtifactCaptures
ADRWhy a significant architectural decision was made
CHANGELOGWhat changed in which version (curated list)

Changelog entries may reference ADR numbers when helpful. ADRs do not replace changelog entries.

Release automation​

Operational bump-and-release mechanics (scripts, CI verify jobs, tag discipline) are defined in ADR-0004. This ADR defines changelog and semver content standards; ADR-0004 defines how releases are produced in CI.

Consequences​

Positive​

  • Consistent release communication across A2C-governed projects
  • Clear separation between decision history (ADRs) and release history (changelog)
  • Enables bump_release.py-style workflows and consumer version adoption

Negative​

  • Maintainers must curate [Unreleased] during development, not only at release time
  • Trivial changes require judgment about release relevance

References​