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
Linux strict security lane (G-C) / strict isolation escape matrix (push) Waiting to run
ci/woodpecker/push/woodpecker Pipeline was successful
Add tools/ci/release_evidence.py (marqdo.release-gates.v1) plus unit tests: missing/skipped/FAIL/UNVERIFIED and tested_sha mismatches stay DO_NOT_RELEASE, performance may be PASS/WARN, unknown gate names are rejected. The GitHub CI now has a release-evidence job that maps the Linux/schema and native matrix results onto the manifest and uploads it, and both CI systems run the evidence-tool tests. Clear the contradictions the RFC calls out: remove the stale CURRENT.md rows that claimed DNS/TLS/UDP and fs metadata were absent while the same table said they were implemented; correct docs/ci.md to state that the GitHub-hosted Windows/macOS matrix exists (Woodpecker has no such agent); keep the old convergence plan historical; require the evidence manifest in releasing.md; and add a docs-consistency guard for these claims. This is step 6 of the CI/security RFC (B05/B06/B07).
132 lines
5.5 KiB
Markdown
132 lines
5.5 KiB
Markdown
# Releasing Marqdo CLI
|
|
|
|
This document describes the release-candidate procedure. It does **not** grant
|
|
permission to tag or publish; that requires explicit owner approval and a green
|
|
required CI matrix on the exact commit.
|
|
|
|
## 1. Preconditions
|
|
|
|
- All applicable gates in
|
|
[`STABLE_RELEASE_IMPLEMENTATION.md`](STABLE_RELEASE_IMPLEMENTATION.md) are
|
|
PASS, and `docs/evidence/ci/<SHA>/manifest.json` has
|
|
`release_decision: RELEASE_CANDIDATE` with every gate's `tested_sha` equal to
|
|
the release SHA. The manifest is produced by
|
|
`tools/ci/release_evidence.py`; a missing, skipped, timed-out or
|
|
SHA-mismatched gate is not PASS.
|
|
- **Language migration is closed through the release SHA.** The source language
|
|
is [RFC-LANG-0002](architecture/RFC-LANG-0002-unified-semantics.md); the
|
|
release notes must state that this is a **breaking** change and that pre-RFC
|
|
`.mq.md` sources are not executable (no `--legacy` path). The migration
|
|
inventory is 100% classified, `stdlib/**/*.mq.md` and examples are migrated,
|
|
and executable-source tests are green at `ffd1cc9`; re-run them for the actual
|
|
release SHA. Platform and strict-lane evidence are still required before this
|
|
is a releasable state; see [`STATUS.md`](STATUS.md) and
|
|
[`migration/README.md`](migration/README.md).
|
|
- G-C is either PASS with a security-lane URL **and** a
|
|
`strict-evidence.json` whose `tested_sha` is the release SHA, or the release
|
|
explicitly says strict isolation is unavailable with owner approval. Never
|
|
claim G-C from a local root/sudo run, a container, or a TCG/QEMU timing run.
|
|
See [`security-gate.md`](security-gate.md) and [`security-vm.md`](security-vm.md).
|
|
- G4 performance is `MEASURED` on the fixed node with `--approved-node`, or
|
|
explicitly `UNVERIFIED`/`WARN` with the reason recorded. Never copy a
|
|
development-container or TCG number. See [`performance.md`](performance.md).
|
|
- `git status --porcelain` is clean apart from intended release files.
|
|
- `Cargo.lock` is committed and the build uses `--locked`.
|
|
|
|
## 2. Build verification
|
|
|
|
```bash
|
|
export PATH="$HOME/.cargo/bin:$PATH"
|
|
cargo fmt --all -- --check
|
|
cargo clippy --workspace --all-targets -- -D warnings
|
|
cargo test --workspace
|
|
cargo build --release --locked -p marqdo-cli
|
|
```
|
|
|
|
## 3. Artifact creation
|
|
|
|
The artifact is a tarball containing the binary, license, README, changelog,
|
|
compatibility matrix, specs, examples and the public protocol consumers. Build
|
|
it from the repository root:
|
|
|
|
```bash
|
|
version="$(cargo metadata --no-deps --format-version 1 \
|
|
| python3 -c 'import json,sys; print(json.load(sys.stdin)["packages"][0]["version"])')"
|
|
target="$(rustc -vV | sed -n 's/^host: //p')"
|
|
stage="dist/marqdo-${version}-${target}"
|
|
rm -rf "$stage"
|
|
mkdir -p "$stage"
|
|
install -m 0755 target/release/marqdo "$stage/"
|
|
cp LICENSE* CHANGELOG.md COMPATIBILITY.md README.md "$stage/"
|
|
cp -r spec examples "$stage/"
|
|
mkdir -p "$stage/tests"
|
|
cp -r tests/consumers "$stage/tests/"
|
|
tar -C dist -czf "dist/marqdo-${version}-${target}.tar.gz" "$(basename "$stage")"
|
|
sha256sum "dist/marqdo-${version}-${target}.tar.gz" \
|
|
| tee "dist/marqdo-${version}-${target}.tar.gz.sha256"
|
|
```
|
|
|
|
If the repository has no `LICENSE*` files at release time, do not silently
|
|
skip the license requirement: add them before shipping.
|
|
|
|
## 4. Clean-install smoke
|
|
|
|
Run in a fresh directory (not the source tree). The example commands below
|
|
assume the examples are migrated to RFC-LANG-0002 and accepted by the frozen
|
|
binary; a failing example run is a release blocker, not a known migration
|
|
artifact:
|
|
|
|
```bash
|
|
tmp="$(mktemp -d)"
|
|
tar -C "$tmp" -xzf dist/marqdo-*.tar.gz
|
|
cd "$tmp"/marqdo-*
|
|
./marqdo --version
|
|
./marqdo --help >/dev/null
|
|
./marqdo check examples/multi-module/index.mq.md
|
|
./marqdo run examples/hello.mq.md
|
|
./marqdo call examples/factorial.mq.md 阶乘 --arg n=5
|
|
./marqdo check examples/multi-module/index.mq.md --refs --emit analysis.json
|
|
./marqdo run examples/multi-module/index.mq.md --trace-file trace.json
|
|
python3 tests/consumers/analysis_consumer.py analysis.json
|
|
python3 tests/consumers/trace_consumer.py analysis.json trace.json
|
|
python3 tests/consumers/validate_protocols.py analysis.json trace.json \
|
|
examples/tool-unknown-name/tool.json
|
|
```
|
|
|
|
Also verify the SHA-256 file before extraction:
|
|
|
|
```bash
|
|
sha256sum -c dist/marqdo-*.tar.gz.sha256
|
|
```
|
|
|
|
## 5. Tagging and publication
|
|
|
|
Only after the above and the remote CI matrix are green on the release commit:
|
|
|
|
```bash
|
|
git fetch origin --tags
|
|
test "$(git rev-parse HEAD)" = "$(git rev-parse origin/master)"
|
|
git tag -s "v${version}" -m "Marqdo CLI v${version}"
|
|
git push origin "v${version}"
|
|
# upload the tarball and .sha256 to the release
|
|
```
|
|
|
|
Do not force-push, do not tag a red commit, and do not upload macOS/Windows
|
|
binaries unless those platform lanes actually passed.
|
|
|
|
The current `0.1.0` candidate at `8af7262` is **not** releasable: it has local
|
|
Linux/VM evidence and a checksummed Linux RC, but no same-SHA GitHub CI or
|
|
self-hosted G-C URL. See
|
|
[`evidence/RELEASE_CANDIDATE_0.1.0_8af7262.md`](evidence/RELEASE_CANDIDATE_0.1.0_8af7262.md).
|
|
|
|
## 6. Rollback
|
|
|
|
- If an asset fails verification: delete the release asset and keep the tag
|
|
only if source/tag integrity is unaffected; otherwise publish a revised
|
|
patch release and mark the old one withdrawn.
|
|
- If a platform regresses: remove that platform from the supported matrix in
|
|
`COMPATIBILITY.md` and the release notes, fix, and re-run the gate. Never
|
|
delete the failing test.
|
|
- If the security gate regresses: set strict back to `Unavailable`, publish a
|
|
security note, and do not claim isolation until the lane is green again.
|