Skip to content

Release Playbook

NON-NORMATIVE. Steps to publish npm packages and create GitHub releases.

When to bump

  • Per-package semver: Each of agentic-math, mcp-server, cli, and plugin-bundle has its own version in packages/<pkg>/package.json. Bump when that package has user-facing or fix changes (patch/minor/major).
  • Which packages: Bump only the packages that changed. Other packages keep their current version; the release workflow publishes whatever version is in each package.json.

Tag strategy

  • Single tag per release: Use one tag vX.Y.Z (for example v0.1.3) for the whole repo. The tag triggers .github/workflows/release.yml. The tag value is independent of individual package versions: for example, tag v0.1.3 can ship cli 0.1.3, mcp-server 0.1.2, and agentic-math 0.1.1.
  • Release notes: Document which package versions are included in the release, either in the GitHub Release body or in docs/release-notes/README.md.

Steps

  1. Bump versions in packages/<pkg>/package.json for each package you are releasing.
  2. Add or update release notes in docs/release-notes/<pkg>-<x-y-z>.md (for example cli-0-1-3.md). Include frontmatter with last-verified: YYYY-MM-DD.
  3. Run release cadence check locally:
python scripts/governance/release_cadence_check.py --check

Fix any reported issues (missing release note, missing or stale last-verified). 4. Capture documentation evidence for the release:

  • Update any authoritative docs whose runtime surface changed in the release (for example docs/architecture/overview.md, docs/integrations/platform-services.md, docs/runbooks/deployment.md, or docs/security/security-posture.md).
  • Run python scripts/docs_contract.py --check --working-tree.

  • If a narrow exception is required, add it to .morphism/policies/docs_contract_waivers.json and cite the waiver id in the PR.

  • Run full CI by either pushing to a branch and opening a PR, or running npx turbo typecheck lint test and pytest tests/ locally. Merge when green.

  • Create and push the tag (from main):
git tag -a v0.1.3 -m "Release v0.1.3"
git push origin v0.1.3
  1. Release workflow runs: full CI, build TypeScript, publish npm, build Python, publish PyPI, and create the GitHub Release with auto-generated notes and Python artifacts.

Attaching human-written release notes to the GitHub Release

  • The workflow uses gh release create ... --generate-notes, so the release body is auto-generated from commits. To add human-written notes:
  • After the release is created, edit the release in the GitHub UI and paste or link content from docs/release-notes/*.md, or
  • Extend the workflow to build a body from docs/release-notes/ (for example by concatenating the files for the versions being released) and pass it to gh release create ... --notes-file. That requires mapping the tag to package versions in the workflow.

Version alignment

  • Packages can be at different versions, for example agentic-math 0.1.1 while cli is 0.1.2. There is no requirement to bump all packages together. Align when you want a single release train; otherwise bump only what changed.

Optional: validate before tag

Run the same checks CI runs:

python scripts/policy_check.py --mode ci --explain
python scripts/governance/release_cadence_check.py --check
python scripts/docs_contract.py --check --working-tree

If any check fails, fix before creating the tag.