GitHub
title
Release checklist
kind
sop
triggers
tools

Standard Operating Procedure: Release

Use with agent-release. Pipeline shape (verify on PR and main, promote, changelog push-back): profile-pipeline.

This kit ships as a git checkout (install.sh / KIT_REF), not npm. Versioned artifacts are GitHub Releases (vX.Y.Z tags). Changelog generation uses git-cliff (same stack as ArchLens).

1. Quality gates

  • Functional impact map aligned; no silent catalog rewrites
  • XFN matrix complete; every apply row green or BLOCKED with owner
  • Security + arch-drift findings addressed or explicitly deferred
  • Pre-commit / CI green on the release revision

2. Human-facing package

  • Conventional PR title (conventional-commits.md); squash-and-merge uses it on the default branch
  • Changelog / release notes: user-visible behavior, migrations, flags
  • Rollback: previous version / flag off / migration reverse notes

Kit release automation

Pipelines (keep these separate on purpose):

PipelineWorkflowWhen
Verify → Promote.github/workflows/ci.ymlPR / main / workflow_dispatch
Pages.github/workflows/deploy-pages.ymlDocs-site path changes on main
CodeQL.github/workflows/codeql.ymlPR / main / weekly
Live EDD.github/workflows/edd-live.ymlNightly schedule

After green Verify on main, the Promote job:

  1. Detect - bin/release.sh detect looks at conventional commits since the last v* tag.
    • feat → minor, fix/perf/refactor → patch, ! / BREAKING CHANGE → major
    • docs / chore / ci / test alone do not cut a release
  2. Publish - creates a GitHub Release with version-scoped notes (bin/release.sh publish): commits since the previous tag only, headed ## vX.Y.Z (never [unreleased])
  3. Sync notes - bin/release.sh sync-notes rewrites every existing vX.Y.Z GitHub Release body from previous-tag..this-tag (idempotent repair)
  4. Changelog - regenerates date-grouped CHANGELOG.md via pnpm changelog (bin/changelog-render.mjs) and commits chore(changelog): … when needed. CHANGELOG stays date-grouped; GitHub Release notes stay version-scoped.

Local:

pnpm changelog                         # regenerate date-grouped CHANGELOG.md
pnpm release:detect                    # print whether HEAD would release
bash bin/release.sh notes              # preview notes since last tag → HEAD
bash bin/release.sh notes '' v1.0.0    # first-release range (beginning → tag)
bash bin/release.sh notes v1.0.0 v1.1.0
bash bin/release.sh sync-notes         # repair GitHub Release bodies (needs GH_TOKEN)

Consumers pin installs with KIT_REF=vX.Y.Z (see install.sh).

3. Ops handoff

  • Load SLOs mapped to telemetry (or N/A) per handover_telemetry.md
  • Docs/runbooks updated when operators or public API changed (agent-docs)
  • Report catalog + XFN summary to the user before calling Release COMPLETE

Markdown source