ADR-0014: Release management with releases.toml
Status: accepted | Date: 2026-01-17
References: ADR-0013, RFC-0000:C-WORK-DEF
Context
To generate a CHANGELOG.md from work items, we need version information. Work items have completed dates but no version. Version is a release-time concept, not a work-time concept. We need a way to track which work items belong to which release without mutating completed work items.
Decision
Store release history in a single gov/releases.toml file with explicit work item references:
[[releases]]
version = "0.2.0"
date = "2026-01-17"
refs = ["WI-2026-01-17-029", "WI-2026-01-17-008"]
The govctl release <version> command collects all done work items not yet in any release and adds them to a new release entry. The govctl render changelog command generates CHANGELOG.md grouped by release version and category.
Consequences
Completed work items remain immutable. Explicit refs list eliminates ambiguity about release membership. Single file is simpler than per-release artifacts. Unreleased work items appear under [Unreleased] section in changelog.
Alternatives Considered
Add version field to work items after release- Store releases in single
gov/releases.tomlwith explicit refs