Files
marqdo-cli/docs/releasing.md
T
cflmy 2c7c4f31e7
Linux strict security lane (G-C) / strict isolation escape matrix (push) Waiting to run
ci/woodpecker/push/main Pipeline was successful
ci/woodpecker/manual/performance Pipeline was successful
CI / fmt + clippy + test (Linux x86_64) (push) Waiting to run
CI / schema instance validation + consumers (push) Waiting to run
CI / runtime contract (macos-latest) (push) Waiting to run
CI / runtime contract (windows-latest) (push) Waiting to run
release(3.0.0-beta.1): product version migration, beta gates, archive tooling and developer docs
REL-01: workspace/CLI/Analysis product version 3.0.0-beta.1 with updated
Cargo.lock; project.marqdo is enforced against the running core with
package.marqdo_range_invalid/package.marqdo_incompatible fail-closed
diagnostics; Tool SemVer prerelease negotiation tests; init template and
examples use the beta range. Verify init derives the project name from the
target directory instead of falling back to 'example'.

REL-02: beta support matrix is Linux x86_64 only; macOS/Windows are explicitly
experimental/unclaimed; strict policy and G4 Beta-only WARN are documented for
the release evidence.

REL-03: deterministic release packaging (tools/release/package.py) ships the
CLI and provider worker together with SOURCE_SHA, RELEASE_INFO.json,
known-limitations, specs, developer docs, examples incl. built plugin/provider
artifacts and consumers; tools/release/smoke.py cold-install tests the archive.

REL-04: docs/developers entry pages; corrected and self-contained third-party
integration handbook; stale Proposed/native-only/informational spec claims
fixed; release/status/compatibility/changelog/releasing docs updated.

REL-05: release_evidence.py gains an explicit beta profile
(BETA_RELEASE_CANDIDATE) distinct from the stable profile; Woodpecker build
step now packages and smoke-tests the archive on every pipeline.

Adds a runnable Resource Provider v2 example and corrects check --emit to
Analysis v2.
2026-11-22 02:31:32 +08:00

10 KiB

Releasing Marqdo CLI (3.0.0-beta.1 and later)

This document is the release-candidate procedure. It does not grant permission to tag or publish: a tag requires the gates below to be green on the exact commit and an explicit maintainer sign-off recorded in the release notes.

Two profiles are deliberately separate (see MARQDO_3_0_PRERELEASE_PLAN.md §3):

  • beta — a prerelease (-beta.N) on the platform(s) the project can really test and fix. Known non-security gaps are allowed only when explicitly recorded. 3.0.0-beta.1 claims Linux x86_64 (glibc) only.
  • stable — 3.0.0/LTS. Not covered by beta exceptions; see STABLE_RELEASE_IMPLEMENTATION.md (historical roadmap input) and the public support matrix.

The binary release pipeline uses the Gitea remote git.cflmy.cn/cflmy/marqdo-cli and Woodpecker ci.cflmy.cn. .woodpecker/main.yml runs on push/pull_request, so a tag push alone does not build release assets; build the archive from the tagged commit on Linux x86_64 and attach it to the Gitea release. Do not publish binaries built from a different checkout.

1. Beta preconditions (non-waivable)

Freeze one release SHA first; any later source change creates a new SHA and requires re-running every gate. On that SHA:

  1. git status --porcelain is clean; Cargo.lock is committed; all builds use --locked.
  2. cargo fmt --all -- --check, cargo clippy --workspace --all-targets -- -D warnings, cargo test --workspace --locked PASS.
  3. cargo build --release --locked -p marqdo-cli -p marqdo-provider-worker PASS; both binaries carry the same target triple and source SHA.
  4. The same-SHA Woodpecker Linux pipeline PASS (fmt, clippy, tests, Windows cross-target compile gate, release build).
  5. Frozen-binary external conformance: build the release binary first, then run the independent fixtures from marqdo-extension-conformance against it and write docs/evidence/extension/<40-hex-release-sha>/manifest.json with tools/ci/verify_extension_contracts.py. The CLI binary hash must not move during the suite. All seven mandatory result categories PASS.
  6. Strict policy (beta gate 5): either same-SHA strict-evidence.json from the disposable VM (outcome: PASS, non-root uid) for Linux strict L1, or an explicitly tested fail-closed strict: unsupported policy in the release notes. A local root/container-only PASS is never promoted to a remote claim; if the evidence is local-VM-only, say exactly that.
  7. G4 performance (beta gate 6): correctness-verified MEASURED report on the fixed Woodpecker agent. If the fixed node is still a shared/powersave host, the maintainer may approve a Beta-only WARN and must publish the environment and limits; the 9 correctness workloads must still pass. Never report TCG/QEMU or development-container timings as G4.
  8. README, CHANGELOG, COMPATIBILITY, docs/STATUS, this file, spec/tool-v1.md, spec/plugin-abi.md and the developer docs are on the same fact baseline. No "implemented but says Proposed", no "released but says DO NOT RELEASE", no product/protocol/package version confusion.
  9. Every shipped binary was actually built and smoke-tested on its claimed platform. The archive records SHA256, SOURCE_SHA, toolchain and known limitations; checksums are integrity, not publisher authentication.

Windows/macOS native lanes, strict L2, uv/npm environment creation, registry, JIT and built-in Knowledge/Proof/View are not beta gates; they are listed as unsupported/experimental in developers/release-limits.md.

2. Build and local gate

export PATH="$HOME/.cargo/bin:$PATH"
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace --locked
cargo build --release --locked -p marqdo-cli -p marqdo-provider-worker

Record the toolchain (rustc -vV, cargo --version), the release SHA and the binary SHA256 values; tools/release/package.py writes them into RELEASE_INFO.json.

3. Release archive

The archive is built deterministically from a clean tree at SOURCE_SHA:

version="$(cargo metadata --no-deps --format-version 1 --offline \
  | python3 -c 'import json,sys; print(next(p["version"] for p in json.load(sys.stdin)["packages"] if p["name"]=="marqdo-cli"))')"
sha="$(git rev-parse HEAD)"
python3 tools/release/package.py --version "$version" --source-sha "$sha"
# dist/marqdo-<version>-x86_64-unknown-linux-gnu.tar.gz(+.sha256)

Contents: marqdo and marqdo-provider-worker in the same directory, LICENSE-*, README.md, CHANGELOG.md, COMPATIBILITY.md, RELEASE_INFO.json, SOURCE_SHA, KNOWN_LIMITATIONS.md, spec/, docs/developers/, examples/ (with host-built plugin/provider artifacts so the examples run without a compiler) and tests/consumers/.

Do not publish an archive with only the CLI, with a mismatched worker target, or with a checksum that does not match the bytes.

4. Clean-install smoke (from the archive only)

Run outside the source tree. The script below extracts the archive into a fresh directory and exercises only the shipped binaries:

python3 tools/release/smoke.py \
  --archive dist/marqdo-*.tar.gz

It verifies the .sha256, RELEASE_INFO.json/SOURCE_SHA, offline --version/--help, check/run/call, lock/sync, Analysis v2 and Trace v2 consumers, Tool install/dispatch, native + worker plugin transports, a foreign kernel, Resource Provider v2 through the shipped worker (positive, unauthorized and missing-helper fail-closed), and strict mode when the host actually supports it. A failure is a release blocker.

5. Release evidence manifest

sha="$(git rev-parse HEAD)"
python3 tools/ci/release_evidence.py --profile beta --target-sha "$sha" \
  --gate linux=PASS:$sha:<woodpecker-pipeline-url> \
  --gate strict_vm=PASS:$sha:docs/evidence/<strict-doc> \
  --gate extension=PASS:$sha:docs/evidence/extension/$sha/manifest.json \
  --gate clean_install=PASS:$sha:docs/evidence/<smoke-doc> \
  --gate version_compat=PASS:$sha:<version-test-log-or-pipeline> \
  --gate windows=UNSUPPORTED:$sha:linux-only-beta-support-matrix \
  --gate macos=UNSUPPORTED:$sha:linux-only-beta-support-matrix \
  --gate performance=WARN:$sha:docs/evidence/<g4-doc> \
  --out "docs/evidence/ci/$sha/manifest.json"

BETA_RELEASE_CANDIDATE is the only acceptable decision for a beta tag. A missing, skipped, failed or SHA-mismatched gate is DO_NOT_RELEASE; never hand-edit a manifest to PASS. Stable releases use the default --profile stable and additionally require Windows/macOS PASS and a strict PASS.

6. Tagging and publication (owner approval required)

Only after all gates above are green on the frozen SHA:

git fetch origin --tags
test "$(git rev-parse HEAD)" = "$(git rev-parse origin/master)"
git tag -a "v${version}" -m "Marqdo CLI v${version}" "$sha"
git push origin "v${version}"

Then create the Gitea release for the tag with prerelease: true, attach the tarball and its .sha256, and include the release notes. The notes must state:

  • beta / non-LTS status and the Linux x86_64-only support claim;
  • the breaking RFC-LANG-0002 language change and no legacy path;
  • the strict policy (same-SHA evidence, or strict: unsupported fail-closed);
  • the G4 Beta-only WARN environment and limits when applicable;
  • independently versioned protocols and stdlib/package versions;
  • the checksum-integrity-not-signature caveat and the known-limitations file;
  • the exact source SHA and links to the evidence manifest.

Example Gitea API shape (token with repository release permission; never commit the token):

curl -X POST -H "Authorization: token $MARQDO_GIT_TOKEN" \
  -H 'Content-Type: application/json' \
  https://git.cflmy.cn/api/v1/repos/cflmy/marqdo-cli/releases \
  -d '{"tag_name":"v3.0.0-beta.1","name":"Marqdo CLI 3.0.0-beta.1",
       "prerelease":true,"draft":false,"body":"..."}'
curl -X POST -H "Authorization: token $MARQDO_GIT_TOKEN" \
  -F "attachment=@dist/marqdo-3.0.0-beta.1-x86_64-unknown-linux-gnu.tar.gz" \
  https://git.cflmy.cn/api/v1/repos/cflmy/marqdo-cli/releases/<id>/assets

The tag points at the tested SHA. Evidence files and the final STATUS update may land in a post-release docs commit that references the tagged SHA, so that the evidence never has to claim a SHA it cannot contain. Do not force-push, do not tag a red commit, and do not upload macOS/Windows binaries unless those platform lanes actually passed.

7. Rollback

  • Missing/mismatched gate discovered after tagging: mark the release withdrawn, delete the assets, keep the tag only if source/tag integrity is unaffected, and ship a corrected prerelease (for example 3.0.0-beta.2). Never delete a failing test.
  • Platform regression: remove that platform from COMPATIBILITY.md, the release notes and the archive, then fix and re-run the gate.
  • Security regression: set strict back to fail-closed/unsupported, publish a security note, and do not claim isolation until fresh same-SHA evidence exists.
  • Performance regression: keep the previous fixed-node baseline, record the new WARN/FAIL truthfully, and do not substitute another machine.

8. Extension-ecosystem gate (additional, never a substitute)

The external conformance gate is mandatory for every tag. It proves that an unchanged CLI binary accepts independent .mq.md packages, plugins, foreign kernels, resource providers and CLI tools, and that the negative paths (unauthorized, wrong digest, wrong target, wrong schema, tampered artifact) fail closed. Generate the manifest with tools/ci/verify_extension_contracts.py; its tested_sha must equal the tagged commit and its CLI binary hash must be the shipped binary. See evidence/extension/README.md.

9. Stable releases

The beta exceptions in §1 (platform scope, G4 WARN, strict-unsupported policy) do not apply to 3.0.0 or LTS. A stable release requires every committed feature on the supported platforms to have same-SHA security, compatibility and performance evidence, a public change/migration policy, and a real user-feedback cycle. Until then the product stays a prerelease.