Releasing

STATUS: v1.21.0-dev is a RELEASE CANDIDATE — NOT PUBLISHED, NOT UPLOADED, NOT PUSHED, NOT TAGGED. This document is the release runbook for the project. No publication action is authorized by this document; only the Maintainer can authorize publication, and only then may the steps in Part B be executed.

Part A — Candidate preparation (no publication)

A1. Scope freeze and versioning

• Freeze a candidate from the development line; set VERSION to the candidate version (e.g. 1.21.0-dev) and confirm the specification version in docs/qplus_language_spec.md (e.g. v4.34).
• Confirm the language change list in CHANGELOG.md and add/refresh release notes under the repository (release-notes files are added by release engineering, not by this runbook).
• Historical candidates are immutable: never repack or edit a frozen candidate. v1.1 rc is deprecated (AOT large-i64 silent-miscompile); v1.2 is the compatibility baseline; 1.3, 1.4.0, 1.4.1, 1.4.2, 1.4.3, 1.4.4, 1.4.5, 1.4.6, 1.4.7 and 1.4.8 are candidates, NOT PUBLISHED.

A2. Clean build and anchors

• Run tools/build.sh from a clean tree; confirm reproducibility (second build is byte-identical) and record the five build anchors (build/bqvm, build/bqvm_small, build/qboot.qbc, build/cgtest.qbc, build/cgtest_aot) plus bootstrap/ fixed-point consistency.
• Run tools/test.sh, tools/robustness_test.sh, and the optional drivers (tools/test_async_io.sh, tools/macro_m1_test.sh, portability CI, bench).
• Build the docs site (python3 site/build_site.py) and run its self-test (python3 site/ci/selftest.py); the site must PASS.

A3. Independent acceptance G0–G7

Request an independent acceptance review (separate from the author of the change) covering:

• G0 package/tree hygiene: no generated artifacts, private paths, evidence files, caches, or secrets; required files present; version/spec consistency.
• G1 reproducible clean build and anchors; G2 language/AOT regression; G3 robustness (malformed qbc/AOT inputs, loud fail, no hang);
• G4 concurrency/async/memory checks that were run (state explicitly what was not run, e.g. TSAN);
• G5 AOT boundaries and loud-fail behavior; G6 release gate; G7 residual-boundary review and the non-claims list.

The candidate ships only with a PASS acceptance report and a written non-claims list (see P0_RELEASE_CHECKLIST.md). A failure blocks the candidate.

A4. Release gate and pack assembly

• Run the release gate on the final tar (release_gate.sh --full <tar>), require PASS with zero failures/skips-for-required, run the extended fixture gate where available, verify package determinism, and clean-unpack build/test.
• Assemble the publication pack (release notes, What's New, verification report, SHA256SUMS, manifest, GITHUB_READY, optional editor artifacts).
• Record archive sha256, size, file/entry counts, and all gate evidence; retain evidence per the retention policy in P0_RELEASE_CHECKLIST.md.

A5. Maintainer decision gate (all required)

The Maintainer must decide, with the release manager's recommendation:

• publication approval (release vs. pre-release/preview tag);
• licence/copyright review (Apache-2.0, NOTICE, third-party notices, brand, closed-source OS-kernel boundary);
• platform/repository/org/repo name;
• tagging/publishing destination and visibility;
• GPG/signing/mirror policy (current verification is sha256-only);
• artifacts to upload (tar + .sha256 + SHA256SUMS; optional editor artifacts);
• docs-site deployment and official download-page entry;
• announcement plan/wording/date, including the v1.1 deprecation advisory;
• evidence-retention and post-publication verification owner.

No publication action happens before this gate passes. The candidate remains NOT PUBLISHED until then.

Part B — Publication (only after explicit Maintainer authorization)

1. Re-verify the archive checksum/size against the pack and run sha256sum -c on all published files; re-run GITHUB_READY checks.
2. Create the public repository/visibility change and tag the candidate (pre-release tag recommended for -dev labels), only with written authorization.
3. Create the release; upload the tar, .sha256, SHA256SUMS, release notes, and the non-claims summary. Upload editor artifacts only if the Maintainer approved them; do not publish to a Marketplace without a separate decision.
4. Verify the downloaded artifacts (checksum, size), deploy the docs site, and verify the download page links.
5. Announce only after all of the above, using the approved wording and the non-claims list; include the v1.1 deprecation advisory.
6. Record release evidence (URLs, sha256, gate outputs, dates) and archive it per the retention policy.

Rollback / yank policy

If a published artifact is found defective after authorization: stop promotion, document the defect and affected versions, publish a corrected candidate through the same gate process, and — with Maintainer approval — mark the bad release as withdrawn/yanked in the hosting platform. Do not silently replace checksums or repack a frozen archive; publish a new version with a clear advisory.

Security and embargo

Security fixes follow SECURITY.md. If a defect is security-sensitive, coordinate privately, prepare the candidate and advisory, and publish only after the fix and advisory are ready and the Maintainer approves the disclosure timing.

Status rule

A version label (including -dev) is not a publication claim. Until the Maintainer authorizes publication and Part B completes, every copy must say NOT PUBLISHED (release candidate) and must not state or imply that a release exists, that editor components are published, or that any platform is supported.