Release Procedure

Alef Release Procedure

Cut a new alef version with a verifiable, reproducible procedure. Skip no step. Every release step has a concrete verification — never assume; always check.

When to apply

• User asks to cut/release/publish a new version
• User asks to bump alef version
• After a stack of fix/feat commits that need a version cycle
• After a breaking change is committed (must bump MINOR pre-1.0, MAJOR otherwise)
• When consumer repos need a new pin

Hard rules

1. Always update CHANGELOG.md — every release has a dated heading and one bullet per user-visible change. Move entries from [Unreleased] into the new version section. Group under ### Added, ### Changed (BREAKING), ### Fixed, ### Removed. Never tag a version with an empty section.
2. Always run poly fmt --fix . then poly lint . to fix lint/format issues before publishing. Re-stage anything the formatter rewrites. Only commit with --no-verify if a hook is genuinely broken in a way unrelated to the change — and then file an issue.
3. No AI signatures in commit messages, tag messages, or release notes. No Co-Authored-By: Claude, no Generated by .... Never.
4. Atomic commits — chore(release): X.Y.Z carries only the version bump and changelog roll. Code fixes live in their own commits, merged before the release commit.
5. Add tests for any fix that changed behavior. A release that includes a fix without a regression test is a release that will regress.
6. Use the Taskfile for version setting — never hand-edit Cargo.toml, alef.toml, src/core/template_versions.rs, or schemas/alef.schema.json. task set-version rewrites all four in lockstep.
7. Publish with gh release create — a bare git tag is not a release. The Publish workflow triggers on release: types: [published], so the GitHub release is literally what runs cargo publish; a tag push alone runs nothing at all. This is not theoretical: v0.55.2 and v0.55.3 were tagged and pushed with no release created, and neither ever reached crates.io. Alef ships as a single crate, so one release means exactly one cargo publish — no multi-crate sequencing, no index propagation race.

Procedure

0. Pre-flight

git status              # working tree clean (or only release-prep diffs)
git fetch origin        # inspect freshness without rewriting local commits

If the release branch has diverged from its upstream, stop and ask how to reconcile it. Do not rebase or merge after committing unless the user explicitly asks for it.

1. Update CHANGELOG.md

• Open CHANGELOG.md.
• Move every bullet under ## [Unreleased] into a new section ## [X.Y.Z] - YYYY-MM-DD (today's date, ISO format).
• Re-create an empty ## [Unreleased] heading at the top.
• If the release contains anything tagged ! (breaking) in commit messages, surface it under ### Changed (BREAKING) with explicit migration guidance.
• Verify no entries are lost: git diff CHANGELOG.md should show only adds in the new section + the moved bullets.
• When folding scratchpad or agent-drafted bullets into a section, strip every heading line from the source first — write plain bullets only, never nested #/## lines. A stray heading from a pasted source reparents everything below it under the wrong version. Before and after any CHANGELOG edit, grep -c '^## \[' must be unchanged and grep -c '^# ' must be exactly 1 (the file's single top-level title).
• poly fmt --fix CHANGELOG.md has previously demoted every heading below the first (rumdl's autofix for a second level-1 heading treats it as a title and reparents everything that follows). poly.toml's [fmt.markdown.rumdl] disable already includes "MD025" as the guard — do not remove it. Re-run the grep -c '^## \[' / grep -c '^# ' check after any poly fmt pass over this file regardless.

2. Set the version via Taskfile

task set-version -- X.Y.Z           # bumps Cargo.toml, alef.toml, ALEF_REV; regenerates
                                    # schemas/alef.schema.json; runs cargo update

The set-version task is the only sanctioned way to bump versions in this repo. It rewrites Cargo.toml (package.version), alef.toml (alef_version), and src/core/template_versions.rs::ALEF_REV, regenerates schemas/alef.schema.json (cargo run -- schema --schema-version), then runs cargo update — all in one shot. Never hand-edit any of these — they must stay in lockstep. The regenerated schema shows up in the release diff (its $id and version both carry the new version); that is expected output, not drift.

After the task finishes, verify:

grep -E '^version' Cargo.toml                       # package version
grep -E '^alef_version' alef.toml                   # alef.toml mirror
grep ALEF_REV src/core/template_versions.rs        # template version pin
grep '"version"' schemas/alef.schema.json           # regenerated schema

All four must match X.Y.Z (the ALEF_REV line and the schema $id both include a leading v).

3. Lint pass

poly fmt --fix .
poly lint .

Re-stage any files the formatter rewrote. If a lint fails for a real reason, fix that reason — never bypass with --no-verify to push past a lint failure.

4. Tests for changed behavior

For every fix: or feat: rolled into this release, confirm there is a test that would have caught the bug or covers the new surface. Add the test now if missing — release commit goes on top.

5. Commit

git add -A
git commit -m "chore(release): X.Y.Z"

The commit subject is exactly chore(release): X.Y.Z. No body unless the release is large enough to warrant a summary; never add AI attribution.

If gitfluff or another commit-msg hook rewrites the subject in an unhelpful way, prefer fixing the hook config over --no-verify. When the user has explicitly authorized --no-verify for this run, document which hooks were skipped in the release notes.

6. Tag and publish

Push main before tagging. Tagging first and pushing second means a rebase or a rejected push after the tag exists leaves the tag pointing at a commit origin/main never contains — --force-with-lease does not work on tags, so recovering means deleting and recreating the tag. Push main, confirm it landed, then tag against the now-confirmed commit:

git push origin main
git tag -a vX.Y.Z -m "vX.Y.Z"
git push origin vX.Y.Z

Then create the GitHub release — this is the part most likely to be skipped and the most important:

gh release create vX.Y.Z \
  --title "vX.Y.Z" \
  --notes-from-tag \
  --verify-tag

If the changelog entry is rich enough to use as release notes, replace --notes-from-tag with --notes-file <(awk '/^## \[X.Y.Z\]/,/^## \[/' CHANGELOG.md | head -n -1) or build a small notes file from the new CHANGELOG section.

For pre-releases (RC, beta), add --prerelease.