Skip to content

Release automation: flat CHANGELOG.md fallback for maintenance releases #496

@hdamker

Description

@hdamker

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.

Metadata

Metadata

Assignees

Labels

enhancementNew feature or requestrelease automationRelated to the implementation or introduction of new release automation

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions