Skip to content

[Chore] CHANGELOG.md drifts between dev and main after release cut (release-flow corollary) #173

@atlas-apex

Description

@atlas-apex

Driver

Surfaced cutting v1.2.0 (the first release under the dev/main release-cut model — AgDR-0007). The release flow is:

  1. Daily PRs land on dev (no CHANGELOG entry per-PR).
  2. Release PR (e.g. release/v1.2.0) branches off dev, adds the CHANGELOG entry, and squash-merges to main.

After step 2, main has the v1.2.0 CHANGELOG section but dev does not. The release branch's CHANGELOG commit was merged into main; dev's working tree is unchanged. The next release PR cut from dev would build a v1.3.0 section on top of v1.1.0 (skipping v1.2.0 entirely from dev's running history) unless the operator manually re-fetches main's CHANGELOG first.

This is a real flaw in the dev/main flow as currently implemented. AgDR-0007 didn't anticipate this side-effect.

Scope

Two complementary fixes:

A. Sync dev's CHANGELOG.md to match main (immediate)

One-file commit on a chore/... branch off dev. Copy CHANGELOG.md from upstream/main to dev so the v1.2.0 section is present on both branches. The diff is exactly the new v1.2.0 section being prepended to dev's existing CHANGELOG.

B. Update /release skill to source the previous CHANGELOG from main (longer-term)

The /release skill's step 3 ("Generate the CHANGELOG draft") currently reads from dev's tip when computing the new entry's position. After this PR lands, the next release cut should:

  • Fetch upstream/main's CHANGELOG.md
  • Prepend the new release's section to that
  • OR back-merge main → dev before generating the draft

Either approach prevents the same drift from recurring next release. Worth picking one and updating the skill.

Acceptance Criteria

  • dev's CHANGELOG.md matches upstream/main's CHANGELOG.md exactly after this PR merges
  • Spot-check: the v1.2.0 section is present at the top of dev's CHANGELOG, followed by v1.1.0, v1.0.0, etc. — same ordering as main
  • No other file changes in the PR (single-file scope)
  • Follow-up scope (B) captured in the PR description as "next ticket" so it doesn't get lost

Risks / Dependencies

  • Tiny scope. Single-file copy.
  • No mechanism change. Pure history-sync between two branches the framework owns.
  • Refs AgDR-0007 — the release-cut model decision; this fix is a missed corollary of that decision.
  • Surfaced 2026-05-04 cutting v1.2.0 (PR release(#160): v1.2.0 #172).

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Medium — plan-worthy, not urgent

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions