/version-release

name: version-release
description: Choose and apply the correct semantic version bump for this repository. Use for every user-visible release, before merge when a change set should ship as patch, minor, or major, and whenever package/plugin/desktop version metadata must stay synchronized.

Version Release

Use Semantic Versioning as the repository-wide release rule:

• **Patch** (`X.Y.Z+1`) for backward-compatible bug fixes, documentation-only changes, dependency/security maintenance, internal refactors, and small user-visible improvements that do not create a substantial new capability.
• **Minor** (`X.Y+1.0`) for backward-compatible feature additions or meaningfully larger product capabilities, including new workflows, pages, integrations, API fields/routes, or major UX surfaces.
• **Major** (`X+1.0.0`) for backward-incompatible behavior, removed/renamed public contracts, required migrations, or fundamental product/architecture changes.

When a change fits more than one category, use the highest applicable bump. When uncertain between adjacent categories, prefer the higher bump or ask the user before releasing. Never infer the bump from commit count, diff size, or elapsed time alone. When the user explicitly requests a concrete version, that instruction overrides automatic classification. State the override and synchronize the requested version exactly.

Automated release preparation

Use the manual **Prepare Release Bump** workflow for routine releases. Its repository-specific input names are intentionally different from standard SemVer labels:

• `major` increments the first component: `X.Y.Z` to `X+1.0.0`.
• `intermediate` increments the standard SemVer minor component: `X.Y.Z` to `X.Y+1.0`.
• `minor` increments the standard SemVer patch component: `X.Y.Z` to `X.Y.Z+1`.

Preview the exact plan locally without writes:

node scripts/bump-release.js intermediate --dry-run --json

The workflow creates one branch, one coordinated commit, the exact open milestone, and one pull request. It also assigns that milestone to every merged default-branch PR that does not already have a milestone, including older omissions, while preserving existing assignments. Every automation-created commit ends with `Co-authored-by: hoangsonww <124531104+hoangsonww@users.noreply.github.com>`. It requires the repository setting **Allow GitHub Actions to create and approve pull requests**, checks that prerequisite before remote writes, and keeps default workflow permissions read-only. It explicitly dispatches CI, file-header, and CLA checks because repository-token PR creation does not emit secondary workflow events. It never merges, force-pushes, tags, or publishes. Existing default-branch CI publishes only after a maintainer merges the PR.

CCAM release workflow

1. Read the current root `package.json` version and summarize why the change is patch, minor, or major. 2. Update the root `package.json` and root lockfile. 3. Mirror the shipping version in `desktop/package.json` and `desktop/package-lock.json`. 4. Update the OpenAPI version example in `server/openapi.js`, then run `npm run openapi:yaml`. 5. Update the deployment surface, which carries the release in many places: `docker-compose.yml` (`ccam-dashboard` and `ccam-mcp` image tags), `deployments/helm/agent-monitor/Chart.yaml` (`version` **and** `appVersion`), every `deployments/kubernetes/**` manifest (`app.kubernetes.io/version` labels, `image:` tags, kustomize `newTag`), and `deployments/scripts/deploy.sh` (the `--tag` example and the `sed` image substitution). 6. Update the version shown in `DEPLOYMENT.md` and `docs/DEPLOYMENT.md` (the `ccam-dashboard:<version>` substitution example) and in `CITATION.cff` (`version:`). 7. Update version-sensitive UI snapshots when the rendered release string changes (the dashboard renders `UI build v<version>`; regenerate with `cd client && npx vitest run -u` and confirm the diff is only the version line). 8. Run `npm run extensions:sync` so every Claude/Codex plugin manifest and marketplace stays on the root release. 9. Update release/version documentation only where the concrete version is intentionally shown. 10. Create or reuse the open GitHub milestone named exactly `v<version>` for the new root version. Query all milestones before creating one. If an exact-title milestone already exists and is closed, stop and verify whether that version has already shipped instead of creating a duplicate. 11. Only after the new-version milestone step completes, paginate every pull request merged into the default branch and assign its returned numeric milestone ID to each PR with no milestone, including older omissions from earlier releases. Preserve every existing milestone assignment, verify each write with a fresh read, and fail if a final paginated query finds any merged PR still unmilestoned. 12. Identify the current open pull request containing the bump and assign it to that milestone. Read `closingIssuesReferences` from the PR and assign every linked closing issue to the same milestone. If the branch has no PR yet, create/reuse the milestone now and treat PR/issue assignment as an incomplete release step until the PR exists. 13. Verify the milestone on the PR and every linked issue with fresh GitHub reads. Do not infer completion from a successful edit command alone. 14. Run `npm run extensions:validate`, relevant tests/builds, and `ccam version` or `node bin/ccam.js version`. 15. Confirm only independently shipped packages remain on their own versions; do not bump `client`, `mcp`, `monitoring`, or VS Code extension packages unless those products are also being released.

The authoritative surface list

`server/__tests__/release-version-consistency.test.js` is the machine-checkable contract for a release bump. **Read it first and run it last** — it is more reliable than this document, because it fails when a surface drifts:

node --test server/__tests__/release-version-consistency.te