Problem description
The release automation changelog generator currently always writes new release
sections to CHANGELOG/CHANGELOG-r{cycle}.md. For repositories that have not
yet migrated their pre-automation history into per-cycle files, this creates a
split between a flat CHANGELOG.md (holding the previous public releases in
the cycle) and a new CHANGELOG/CHANGELOG-r{cycle}.md (holding only the
maintenance entry), which is surprising for readers of the maintenance release.
Triggered by a concrete case: SimpleEdgeDiscovery plans a maintenance release
to patch the Fall25 public release (r2.2) with a schema-reference fix
(simple-edge-discovery 2.0.1). Its current CHANGELOG.md contains the full
release history including r2.2; the expectation is that the maintenance
entry lands in the same file.
Possible evolution
Extend the changelog generator and post-release syncer with a narrow
maintenance-mode fallback:
- If
release_type == "maintenance-release" AND
CHANGELOG/CHANGELOG-r{cycle}.md does not exist → write/sync flat
CHANGELOG.md at the repository root.
- Otherwise → keep the per-cycle default (
CHANGELOG/CHANGELOG-r{cycle}.md).
The same rule drives the CHANGELOG URL rendered into the README release-info
section (blob/main/CHANGELOG.md vs tree/main/CHANGELOG).
Effect:
- New release cycles on any repo continue to use the per-cycle structure.
- Maintenance releases on repos that have not yet run
/migrate-changelog
keep prepending to the existing flat file until the history is migrated.
After migration, subsequent maintenance releases in those cycles use the
per-cycle file.
Alternative solution
Run /migrate-changelog on each affected repository before its first
maintenance release. Rejected as the only path because it forces a structural
decision for every pre-automation repository at an awkward moment (a small
patch release), and because the C5 maintenance-branch workflow will benefit
from this same fallback once implemented.
Additional context
Preparation for #356 (C5 maintenance branch releases): C5 will formalize the
maintenance branch model and version/branch validation; the dual-mode
CHANGELOG behaviour proposed here is a prerequisite so that maintenance
releases produce a consistent changelog regardless of whether the repository
has migrated to the per-cycle structure.
Problem description
The release automation changelog generator currently always writes new release
sections to
CHANGELOG/CHANGELOG-r{cycle}.md. For repositories that have notyet migrated their pre-automation history into per-cycle files, this creates a
split between a flat
CHANGELOG.md(holding the previous public releases inthe cycle) and a new
CHANGELOG/CHANGELOG-r{cycle}.md(holding only themaintenance entry), which is surprising for readers of the maintenance release.
Triggered by a concrete case:
SimpleEdgeDiscoveryplans a maintenance releaseto patch the Fall25 public release (
r2.2) with a schema-reference fix(
simple-edge-discovery 2.0.1). Its currentCHANGELOG.mdcontains the fullrelease history including
r2.2; the expectation is that the maintenanceentry lands in the same file.
Possible evolution
Extend the changelog generator and post-release syncer with a narrow
maintenance-mode fallback:
release_type == "maintenance-release"ANDCHANGELOG/CHANGELOG-r{cycle}.mddoes not exist → write/sync flatCHANGELOG.mdat the repository root.CHANGELOG/CHANGELOG-r{cycle}.md).The same rule drives the CHANGELOG URL rendered into the README release-info
section (
blob/main/CHANGELOG.mdvstree/main/CHANGELOG).Effect:
/migrate-changelogkeep prepending to the existing flat file until the history is migrated.
After migration, subsequent maintenance releases in those cycles use the
per-cycle file.
Alternative solution
Run
/migrate-changelogon each affected repository before its firstmaintenance release. Rejected as the only path because it forces a structural
decision for every pre-automation repository at an awkward moment (a small
patch release), and because the C5 maintenance-branch workflow will benefit
from this same fallback once implemented.
Additional context
Preparation for #356 (C5 maintenance branch releases): C5 will formalize the
maintenance branch model and version/branch validation; the dual-mode
CHANGELOG behaviour proposed here is a prerequisite so that maintenance
releases produce a consistent changelog regardless of whether the repository
has migrated to the per-cycle structure.