This process defines when a cxxmcp release can be published and what evidence has to travel with it. It is part of the SDK compatibility contract together with the compatibility policy, public API stability policy, release gates, release notes template, and release candidate checklist.

Versioning

cxxmcp uses semantic versioning for public SDK releases:

MAJOR changes may remove deprecated public APIs, remove protocol snapshots, or change source-level behavior that stable consumers can observe.
MINOR changes may add public APIs, protocol families, transports, package manager routes, and compatibility adapters while preserving source compatibility for the supported major version.
PATCH changes are bug fixes, documentation fixes, compatibility fixes, and packaging fixes that do not add large public API surfaces.

Pre-release tags use alpha, beta, or rc suffixes. Stable release notes must not claim fact-standard status unless the full release candidate checklist is complete for the exact release commit. A technical audit with no open code defects is necessary evidence, but it is not sufficient without the matching release-gates, package-manager, API-doc, source, and performance debt artifacts.

Stage Gates

Each public release has one of these stages:

Alpha: API movement is allowed, but every public SDK movement must be called out in CHANGELOG.md and release notes with stable, experimental, or deprecated classification.
Beta: public SDK APIs should be mostly settled. Breaking changes require a design note or issue, migration text, and explicit release notes.
RC: only bug fixes, release evidence fixes, documentation fixes, and package metadata fixes are allowed unless a failed gate forces a targeted code fix. New public API requires release owner approval and must be additive.
Stable: public source compatibility is frozen for the major version. Breaking public API changes move to the next major release unless they fix a security vulnerability or a protocol compliance issue that cannot be solved additively.

The release candidate checklist is the binding stage review record.

Version Metadata

Use python -B scripts/prepare_release.py <version> for release metadata updates. The script updates the repository version files, package references, release-gates examples, and package-consumption hashes from the same deterministic SDK source archive generator used by release-sdk.

Do not hand-edit the xmake add_versions hash or FetchContent/CPM URL_HASH values for a normal release. The SDK source archive intentionally excludes the external package-index and package-consumption files that contain that hash, so the archive checksum is not self-referential.

Required Release Artifacts

Every public release must attach or link artifacts produced from the exact release commit:

versioned SDK source archive with vendored fallback dependencies
SHA256SUMS.txt for published source artifacts
generated public API documentation
release evidence bundle
release-artifact-review.md generated by scripts/check_release_artifacts.py --review-output after validating the downloaded exact-commit release-gates and release-sdk artifacts
release notes filled from docs/release_notes_template.md
changelog entry for the release
package metadata or package recipe references for the routes advertised by that release

Source packages are the default SDK artifact. Prebuilt binaries are optional and may be published only for matrix entries that passed release-blocking gates for the same commit.

Evidence Boundaries

docs/technical_audit.md records code-defect closure, accepted limitations, and tracked debt. Release owners must review it with todo.md, docs/performance_debt.md, the release evidence bundle, and docs/release_candidate_checklist.md before publishing. Fixed audit findings do not automatically authorize stable, package-registry, or fact-standard claims; those claims require exact-commit artifacts for the advertised compiler/generator matrix, package-manager routes, optional auth/OpenSSL package surfaces, generated documentation, source checksums, and any performance or compile-time statements.

Public API Review

Before tagging a beta, rc, or stable release, review public header diffs under:

sdk/include/cxxmcp
sdk/core/include/cxxmcp
sdk/protocol/include/cxxmcp
sdk/auth/include/cxxmcp when auth is enabled
sdk/client/include/cxxmcp
sdk/server/include/cxxmcp
sdk/transport/include/cxxmcp

The review must follow Public API Stability. It must classify every public change as additive stable API, experimental API, compatible deprecation, behavior clarification, bug/security/protocol fix, or breaking change. For beta, rc, and stable releases, the review record must include:

the public header diff range or compared tags
the classification for each public change
any design note or issue linked to a new stable or experimental surface
migration notes for deprecations and breaking changes
evidence that package-smoke, public-header compile tests, and generated API docs were produced from the same commit

Breaking changes require migration notes and must follow the compatibility and public API stability policies before they ship in a stable line.

Dependency Review

Every release review must record dependency/reference versions from docs/dependency_policy.md and the release evidence manifest. Dependency updates require:

the reason for the update
the package manager route affected, if any
source-package impact for bundled dependencies
compatibility impact for CXXMCP_USE_SYSTEM_DEPS=ON
conformance or package-smoke evidence after the update

SDK package submissions should keep runtime/tooling dependencies outside the core SDK package unless a separate tools package is explicitly created.

Security And Advisories

Security reports follow SECURITY.md. A security release may skip the normal alpha/beta/rc progression only when delaying the fix would increase user risk. Even then, the release notes must identify the affected versions, fixed versions, compatibility impact, and any temporary evidence gaps.

Security fixes that require source-breaking API changes must prefer additive mitigations first. If a breaking change is unavoidable, it is allowed only with clear migration notes and a major-version plan unless the vulnerable API cannot remain available safely.