release-process

name	release-process
description	AI repo versioning and changelogs via release-please — never edit CHANGELOG.md or pyproject version by hand. Use when the user asks about releases, version bumps, changelogs, or preparing a release.
license	MIT
compatibility	claude cursor opencode
metadata	{"version":"1.0.0","languages":"all","audience":"developers","workflow":"documentation","since":"2026-05-22"}

Release process (release-please)

Versions and changelogs in this repo are fully automated. Do not manually edit release artifacts in feature PRs.

What release-please owns

• Every workspace package CHANGELOG.md
• version = "..." in each package pyproject.toml
• .release-please-manifest.json

Config: release-please-config.json and manifest at repo root. Full lifecycle: docs/contributing/release-process.md.

CI guard — do not bypass

.github/scripts/check-no-manual-release.sh fails PRs that modify:

• any CHANGELOG.md
• .release-please-manifest.json
• the version = "..." line in any pyproject.toml

Exception: release-please's own standing Release PR (opened by the Release Workflow App).

What you do in a feature PR

1. Land code with conventional commit subjects (git-conventional-commits skill).
2. Use scopes that match the package path when helpful (e.g. feat(sdk): ..., feat(toolkit): ...).
3. Let release-please accumulate notes on the standing Release PR (title: chore: stable release main per group-pull-request-title-pattern in release-please-config.json; target CalVer is in the PR diff, not the title).
4. Merge the Release PR when ready to ship — release-please rewrites versions, changelogs, tags, and triggers PyPI publish.

Intent	Commit type	Notes
New feature	feat(scope): ...	Appears under release notes
Bug fix	fix(scope): ...	Bug Fixes section
Breaking change	feat(scope)!: ... + BREAKING CHANGE: footer	Major bump per package
Internal deps only	chore(deps): ...	Hidden from user-facing changelog

CalVer scheme: YYYY.WW.PATCH — see docs/contributing/release-process.md.

When the user asks to "bump version" or "update changelog"

Do not edit CHANGELOG.md or pyproject.toml version. Instead:

1. Explain that release-please handles it on the standing Release PR.
2. Ensure their work is committed with the right conventional commit type/scope.
3. Point them to merge the Release PR or read docs/contributing/release-process.md for hotfixes/RC/dev cuts.

Hotfixes on release/*

Backport fixes from main with cherry-pick, not direct edits on the release branch.

Rule	Why
Cherry-pick from main	CI checks patch equivalence (git cherry vs main), not identical SHAs
Rebase and merge only	Squash collapses N commits → 1; release-please loses per-commit changelog entries
Conventional commit subjects	release-please attributes each merged commit to changelog sections
Skip release-please bot PRs	chore: hotfix release/... PRs are automation — CI skips lineage for release-please--* branches

Script: .github/scripts/check-release-lineage.sh (runs in CI for human PRs targeting release/*; patch-equivalence only, no commit-metadata allowlist).

Monorepo consumers (different repo)

Bumping a published unique_toolkit / unique_sdk version inside the monorepo (e.g. assistants-core pyproject.toml) is a separate step after a stable AI release — not a manual ai-repo changelog edit. See model-deployment LESSONS-LEARNED for cherry-pick checklists.

Related skills

• hotfix-backport — cherry-pick workflow and rebase-merge rules for release/*
• git-conventional-commits — commit/PR title format
• security-maintenance — same no-manual-release rules for CVE/CodeQL PRs