# Release Process

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](public_api_stability.md). 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.
