Files
marqdo-cli/docs/releasing.md
T
cflmy 2c7c4f31e7
ci/woodpecker/push/main Pipeline was successful
ci/woodpecker/manual/performance Pipeline was successful
Linux strict security lane (G-C) / strict isolation escape matrix (push) Canceled after 0s
CI / fmt + clippy + test (Linux x86_64) (push) Canceled after 0s
CI / schema instance validation + consumers (push) Canceled after 0s
CI / runtime contract (macos-latest) (push) Canceled after 0s
CI / runtime contract (windows-latest) (push) Canceled after 0s
CI / release evidence manifest (push) Canceled after 0s
CI / release candidate artifact (macos-latest) (push) Canceled after 0s
CI / release candidate artifact (ubuntu-latest) (push) Canceled after 0s
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

214 lines
10 KiB
Markdown

# 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`](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`](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`](https://git.cflmy.cn/cflmy/marqdo-cli) and
Woodpecker [`ci.cflmy.cn`](https://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`](https://git.cflmy.cn/cflmy/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`](developers/release-limits.md).
## 2. Build and local gate
```bash
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`:
```bash
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:
```bash
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
```bash
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:
```bash
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):
```bash
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`](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.