ci: use changie

[conradoplg]

Motivation

Closes #11252

Solution

Introduces changie and updates the CI workflows to work with it.

This PR does the following:

• Move the old changelogs to .changie. That folder keeps the changelog section for each released version, but since we are starting to use it now, the PRs adds one entry with the entire changelog so far.
• Add a header.tpl.md which is the changelog header. Changie generates the final changelog by concatenating the header with the changelog file for each version in the past. To make things simpler I use the same header for zebra and crates, so I reworded it slightly to work with both.
• The rest are adjustments for CI - the changelog gates now needs to check if a changie entry file was added, instead of looking into the changelog itself. This is harder to test so we will need to test by getting this merged and using it, but it shouldn't cause too much friction since the changelog gate is now currently not required to pass in CI.

Tests

Specifications & References

Follow-up Work

After this merges we will need to update all other PRs to add a changie entry instead of editing the changelog directly, which admittedly will be a pain. Note that from now on, any changelog entries will be overwritten at time of release.

AI Disclosure

• No AI tools were used in this PR
• AI tools were used: I initially did the config manually following the changie guide, then I used Claude to make it work with all crates and to update the actions (which to be frank I haven't reviewed thoroughly, the only adjustment I asked was to use the official github action for it instead of a custom one it tried to add)

PR Checklist

• The PR title follows conventional commits format: type(scope): description
• The PR follows the contribution guidelines.
• This change was discussed in an issue or with the team beforehand.
• The solution is tested.
• The documentation and changelogs are up to date.

[v12-auditor]

Warning

No auditable source files found in this PR's diff.

[alchemydc]

Things I checked and confirmed working:

• versionFormat emits ## [Zebra 6.3.0](…/releases/tag/v6.3.0) - DATE for zebrad and ## [13.0.0] - DATE for crates, which is exactly what the unmodified validate-release-changelogs.sh heading matcher accepts. That script correctly didn't need changing.
• changie merge on this branch produces zero drift — I ran it with changie v1.25.2 (the version you pin) against efaf0d3d9 and git status --porcelain came back empty. The history migration is faithful.
• The release.yml batching is idempotent as designed. The git rm --diff-filter=A plus git checkout base -- .changes restore is correct, the "already batched" skip works, merge-base is valid under fetch-depth: 0, and there's no workflow re-trigger loop since release-pr is filtered to pushes on main.
• Leaving zebra-grpc/zebra-scan out of projects: is right, and the comment explaining why is appreciated.

Five findings below, in order of impact. Only the first is something we might consider blocking.

---

1. The rebase will silently delete a live changelog entry

This is the one that loses data, and nothing in the pipeline catches it.

This branch is based on f5c5277fe (chore: release v6.3.0). Since then #11215 landed on main, adding a real curated entry to zebra-consensus/CHANGELOG.md:

## [Unreleased]

### Changed

- Consensus rules that apply to a transaction in both block and mempool context
  are now applied by a single shared `check_common_consensus_rules()` function ([#9301](…)).

This PR ships .changes/unreleased/ with only a .gitkeep, and the migrated history stops at zebra-consensus/v15.0.0.md. So on the final rebase that file conflicts, and the natural resolution — take the changie side, drop [Unreleased] — deletes the entry.

Nothing downstream notices:

• batch-release-changelogs.sh finds no pending fragment for a directly-changed package and writes the mechanical Updated dependencies. fragment instead.
• validate-release-changelogs.sh only checks that the versioned section is non-empty (lines 77-84) — a mechanical entry satisfies that.
• The drift check I suggest in finding 2 can't help either: deleting [Unreleased] is precisely what this migration legitimately does.

Ask: as part of the final rebase, convert every entry still under [Unreleased] on main into a fragment. Today that's the one entry above, but more may land before this merges, so it needs redoing against main at merge time rather than once now. Then diff the recreated Release PR's sections against #11254's to confirm nothing was dropped.

2. Nothing enforces "never edit CHANGELOG.md by hand"

AGENTS.md, copilot-instructions.md and changelog-guidelines.md all now say the changelogs are generated and must not be edited by hand. No CI check enforces it, and the changelog gate was made non-required in #11251.

So a PR can merge with a hand-written CHANGELOG.md hunk, the advisory gate notes a missing fragment, nobody blocks on it, and the entry is silently deleted by the next changie merge. Given every open PR is currently in exactly that shape, this seems worth closing now rather than later.

Suggested fix, no new script needed — a drift check in lint.yml, right next to the changie install this PR already adds there:

- name: Changelogs match .changes
  run: |
    changie merge
    git diff --exit-code

A bare git diff --exit-code rather than a '**/CHANGELOG.md' pathspec: in a clean CI checkout changie merge can only touch changelogs, and the pathspec form is fiddly to get right.

I verified both halves of this: it passes on this branch today (zero drift), and a committed hand edit to zebra-chain/CHANGELOG.md does make it fail, with the edit reverted in the diff. This would be a good one to make required.

3. Fragment hygiene: colliding filenames, and unvalidated kinds

(a) changelog-command.yml tells the model to name fragments <project>-<kind>-<n>.yaml. changie's own default fragmentFileFormat is {{.Project}}-{{.Kind}}-{{.Time.Format "20060102-150405"}} — timestamped precisely because fragments from independent branches must not collide. I confirmed changie new -j zebrad -k Added produces zebrad-Added-20260813-214218.yaml.

Two PRs both told to write zebrad-Added-1.yaml produce an add/add conflict, or a silent overwrite if someone resolves it carelessly. The prompt already has github.event.issue.number in scope, so <project>-<kind>-<PR number>.yaml fixes it.

(b) validate-pr-changelogs.sh validates the fragment's project but not its kind — it only greps .changie.yaml for project keys. A typo'd kind, or the very plausible kind: Breaking Changes (the label the section actually renders as, rather than the breaking key), passes the PR gate and then hard-fails the release run weeks later:

$ changie batch v9.9.9 --project zebrad     # fragment with kind: Fxied
Error: kind not found but configuration expects one: 'Fxied'

Since the whole /changelog flow produces hand-created fragment files, this class of typo is expected rather than hypothetical. The fix is the same shape as the unknown-project check you already wrote.

Minor and related: the project grep ^[[:space:]]+key: ${project}$ also matches the kind key line, so project: breaking false-passes. Your own comment half-acknowledges this.

4. Ordering: #11254 should be closed before this merges

The follow-up note says we'll deal with the other PRs after merging. One ordering detail matters: the open Release PR must be closed before this merges, not after.

release.yml's release-pr job fires on the merge push — the title ci: use changie passes the !startsWith(…, 'chore: release') guard — release-plz force-refreshes the existing release branch, and the new batching step runs against it, all in that same run before anyone can intervene. Your restore-from-base design makes that outcome safe, but closing #11254 afterwards doesn't achieve the goal of keeping the two flows from interleaving.

Migration plan for the rest of the open PRs is filed as #11262.

5. Contributor docs are stale, and there's no path for a new crate

Three small gaps, one owner, one follow-up:

• CONTRIBUTING.md:70 still says "Update CHANGELOG.md for user-visible changes". AGENTS.md (and CLAUDE.md, its symlink) and .github/copilot-instructions.md were updated here; the doc that outside contributors actually read was missed. .github/pull_request_template.md:49 could point at the fragment too.
• Nothing says how to install changie. The docs now tell contributors to run changie new, which is the first thing they'll hit. One line pinned to the same v1.25.2 CI uses would do it.
• There's no documented path for adding a new crate to .changie.yaml, and it's already live: feat(sync): replace the Sync component with a known-hash initial block download engine #10725 adds tower-fair-buffer with a hand-written CHANGELOG.md. Its fragments would be rejected as an unknown project, and adding the project without migrating its history makes changie merge truncate that changelog to just the header — which is exactly what your .changie.yaml comment warns about. The drift check in finding 2 would surface this loudly, which is another argument for adding it.

---

One caveat to accept knowingly, not a finding

This PR rewrites the header of every crate's CHANGELOG.md, and CHANGELOG.md ships inside every published package (cargo package --list -p tower-fallback includes it). release-plz detects changes from packaged-file diffs, so the refreshed Release PR will likely bump all 12 crates — patch, mechanical-entry-only — rather than the current three plus zebrad. Harmless, but worth expecting rather than discovering. I did not verify this by running release-plz, so treat it as an expectation.

---

Review performed with Claude Code. The verification claims above (zero drift, the hand-edit test, the bad-kind error, the base-commit comparison) were produced by actually running changie v1.25.2 against efaf0d3d9 and comparing to current main.

[alchemydc]

Approving. The changie mechanics are sound and I verified the parts that matter most — zero changie merge drift against efaf0d3d9, the generated headings match the unmodified release validator, and the release batching is idempotent.

To be explicit about finding 1 in my review above: I'm leaving it to your judgment whether to handle it pre-merge. The [Unreleased] entry that landed in zebra-consensus/CHANGELOG.md via #11215 will need converting to a fragment during the rebase, or it gets dropped — but that's a rebase-time detail, not a reason to hold up the design. Your call on whether to fold it in now or catch it when you rebase.

Findings 2, 3 and 5 are follow-ups rather than changes to this PR. Finding 4's ordering point (close #11254 before this merges) is the one thing worth acting on at merge time.

Migration plan for the other open PRs is tracked in #11262.

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-08-13 23:00 UTC · Rule: batched · triggered by rule move to any queue if GitHub Rulesets are satisfied
• ✅ Checks passed · on draft merge queue: checking main (8d00077) and #11253 together #11263
• ✅ Merged — 2026-08-13 23:03 UTC · at efaf0d3d9b6dc02948ca05d1210ad20406e8bf9d · merge

This pull request spent 3 minutes 3 seconds in the queue, including 2 minutes 15 seconds running CI.

Required conditions to merge

• #review-threads-unresolved = 0 [🛡 GitHub repository ruleset rule PR Requirements]
  • ci: use changie #11253
• github-review-approved [🛡 GitHub branch protection]
  • ci: use changie #11253
• github-review-approved [🛡 GitHub repository ruleset rule PR Requirements]
  • ci: use changie #11253
• any of [🛡 GitHub repository ruleset rule PR Requirements]:
  • check-success = @github-actions/lint
  • check-neutral = @github-actions/lint
  • check-skipped = @github-actions/lint
• any of [🛡 GitHub repository ruleset rule PR Requirements]:
  • check-success = test-crates
  • check-neutral = test-crates
  • check-skipped = test-crates
• any of [🛡 GitHub repository ruleset rule PR Requirements]:
  • check-success = unit-tests
  • check-neutral = unit-tests
  • check-skipped = unit-tests
• any of [🛡 GitHub repository ruleset rule PR Requirements]:
  • check-success = @github-actions/pr-gate-result
  • check-neutral = @github-actions/pr-gate-result
  • check-skipped = @github-actions/pr-gate-result