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.
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.1claims Linux x86_64 (glibc) only. - stable —
3.0.0/LTS. Not covered by beta exceptions; seeSTABLE_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:
git status --porcelainis clean;Cargo.lockis committed; all builds use--locked.cargo fmt --all -- --check,cargo clippy --workspace --all-targets -- -D warnings,cargo test --workspace --lockedPASS.cargo build --release --locked -p marqdo-cli -p marqdo-provider-workerPASS; both binaries carry the same target triple and source SHA.- The same-SHA Woodpecker Linux pipeline PASS (fmt, clippy, tests, Windows cross-target compile gate, release build).
- Frozen-binary external conformance: build the release binary first, then
run the independent fixtures from
marqdo-extension-conformanceagainst it and writedocs/evidence/extension/<40-hex-release-sha>/manifest.jsonwithtools/ci/verify_extension_contracts.py. The CLI binary hash must not move during the suite. All seven mandatory result categories PASS. - Strict policy (beta gate 5): either same-SHA
strict-evidence.jsonfrom the disposable VM (outcome: PASS, non-root uid) for Linux strict L1, or an explicitly tested fail-closedstrict: unsupportedpolicy 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. - G4 performance (beta gate 6): correctness-verified
MEASUREDreport 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. README,CHANGELOG,COMPATIBILITY,docs/STATUS, this file,spec/tool-v1.md,spec/plugin-abi.mdand 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.- 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: unsupportedfail-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.