Changelog conventions for superbuild consumers
Superbuild workspaces that mount this repository at tools/ai-rules/ keep a root-level
CHANGELOG.md for release-relevant history of the consumer workspace (and each
first-party Git repo under src/ keeps its own changelog when that repo is released
separately).
Canonical specification
Changelog format, when to update, and AI expectations are defined by A2C — not fully duplicated here.
Use the a2c-workflow tag or commit that matches your team's pinned tooling when following
these links; develop URLs below are convenience pointers, not a floating contract.
| Topic | Canonical source |
|---|---|
| Changelog policy | a2c-workflow docs/workflow/changelog-policy.md |
| ADR (requirement) | a2c-workflow ADR-0002 |
| Template | a2c-workflow templates/changelog/CHANGELOG-template.md |
Superbuild-workflow and A2C are different workflows. They share one changelog contract (Keep a Changelog + SemVer) so humans and AI agents use the same file shape.
Requirement (consumers)
| Repository role | Expectation |
|---|---|
| Superbuild consumer (workspace root) | Root CHANGELOG.md — scaffolded by eai-supinit / eai-supmig bootstrap |
Product submodule under src/ | Own CHANGELOG.md when that Git repo is versioned / released on its own |
Standards
| Topic | Standard |
|---|---|
| Format | Keep a Changelog 1.1.0 |
| Versioning | Semantic Versioning 2.0.0 |
Structure (minimum)
# Changelog
All notable changes to this project are documented here.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
### Added
- (nothing yet)
### Changed
- (nothing yet)
### Fixed
- (nothing yet)
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 / deprecations | Mechanical renames invisible to consumers |
| Security fixes |
During development: add bullets under ## [Unreleased] as release-relevant work lands.
At release: move [Unreleased] into ## [X.Y.Z] - YYYY-MM-DD and reset [Unreleased].
ADRs vs changelog
- ADRs (
docs/adr/) record why significant decisions were made — see adr-conventions.md - Changelog records what changed in each version
Link ADR numbers from changelog bullets when helpful; do not paste ADR bodies into the changelog.
AI expectations
| Situation | Expected behavior |
|---|---|
| Bootstrap | Create root CHANGELOG.md from the consumer template if missing |
| Release-worthy change | Propose [Unreleased] updates; apply when approved |
| Routine internal work | Do not touch the changelog unless release-relevant |
| Scaffold / agent handoff | Read this doc and the consumer root AGENTS.md |
Enforcement
A2C's check-changelog pre-commit hook is optional for superbuild consumers unless the
workspace also adopts A2C hooks. Superbuild bootstrap scaffolds the file and documents the
policy; hook enforcement remains an A2C (or local) choice.
This repository
superbuild-workflow dogfoods Keep a Changelog for the eai-sup* packages — see root
CHANGELOG.md and release-pipeline.md. That maintainer flow is separate
from the consumer convention above.