Changelog policy
Normative expectations for CHANGELOG.md in A2C-governed software repositories. Recorded as ADR-0002.
Requirement
Every A2C-governed software repository must version a root-level CHANGELOG.md.
Standards
| Topic | Standard |
|---|---|
| Format | Keep a Changelog 1.1.0 |
| Versioning | Semantic Versioning 2.0.0 |
Purpose
- Human-readable history of notable changes per released version
- Curated release notes — not a raw commit log
- Support for semi-automated release flows (
VERSION, tags,bump_release.py)
Structure
# Changelog
All notable changes to this project are documented here.
The format is based on Keep a Changelog 1.1.0, and this project
uses Semantic Versioning 2.0.0.
## [Unreleased]
### Added
- New feature description
## [1.2.0] - 2026-06-12
### Added
- User-visible capability (see ADR-0005 when relevant)
### Fixed
- Bug fix consumers care about
Use only subsections that apply. Placeholder - (nothing yet) is acceptable in empty [Unreleased] subsections.
When to update
| Update changelog | Skip changelog |
|---|---|
| User-visible features | Internal refactors with no release impact |
| Bug fixes consumers notice | Trivial typo fixes in non-release docs |
| Breaking changes | Mechanical renames invisible to consumers |
| Deprecations and removals | |
| Security fixes |
During development: add bullets under ## [Unreleased] as release-relevant work lands.
At release: move [Unreleased] content into ## [X.Y.Z] - YYYY-MM-DD and reset [Unreleased].
ADRs vs changelog
- ADRs record why significant decisions were made
- Changelog records what changed in each version
Link ADR numbers from changelog bullets when it helps readers; do not duplicate ADR bodies in the changelog.
AI expectations
| Situation | Expected behavior |
|---|---|
| Bootstrap | Create CHANGELOG.md from templates/changelog/CHANGELOG-template.md if missing |
| Release-worthy change | Propose [Unreleased] updates; apply when approved |
| Release flow | Ensure the target version section matches code changes and semver; finalize with bump_release.py per ci-release-flow.md |
| Routine internal work | Do not touch changelog unless release-relevant |
Enforcement
check-changelog from a2c-pre-commit-hooks (ADR-0003) requires CHANGELOG.md to be staged when other files are staged at commit time.
Tag pipelines run release:verify to ensure the git tag matches the project version source (ADR-0004).
This repository
a2c-workflow dogfoods this policy. Maintainer release steps: release-pipeline.md.