From 33005745e77c1263be7a31259a7f70827073d851 Mon Sep 17 00:00:00 2001 From: showxu <10173746+showxu@users.noreply.github.com> Date: Thu, 22 Oct 2026 12:42:35 +0800 Subject: [PATCH] docs: move release facts to the release reference --- AGENTS.md | 4 +- Documentation/Architecture/README.md | 2 - .../Architecture/VersioningAndRelease.md | 87 ------------- Documentation/README.md | 4 +- Documentation/Reference/Release.md | 117 +++++++++++++++--- 5 files changed, 106 insertions(+), 108 deletions(-) delete mode 100644 Documentation/Architecture/VersioningAndRelease.md diff --git a/AGENTS.md b/AGENTS.md index abcd9b3..3a335c8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -69,7 +69,9 @@ Use this check: ## Task Route - Before changing versions, dependencies, packaging or release workflows, read - `Documentation/Architecture/VersioningAndRelease.md` and use its existing project check entry points. + the [organization VERSIONING](https://github.com/computer-mcp/.github/blob/master/VERSIONING.md) + for version rules and `Documentation/Reference/Release.md` for release facts + and check entry points. - For repository-native documentation placement, read `Documentation/README.md` before editing. diff --git a/Documentation/Architecture/README.md b/Documentation/Architecture/README.md index 1c96f6f..5babf0c 100644 --- a/Documentation/Architecture/README.md +++ b/Documentation/Architecture/README.md @@ -1,5 +1,3 @@ # Architecture [Package](Package.md) defines ownership, runtime and distribution boundaries. -[Versioning and Release](VersioningAndRelease.md) defines version authority, -acceptance and publication. diff --git a/Documentation/Architecture/VersioningAndRelease.md b/Documentation/Architecture/VersioningAndRelease.md deleted file mode 100644 index f62a274..0000000 --- a/Documentation/Architecture/VersioningAndRelease.md +++ /dev/null @@ -1,87 +0,0 @@ -# Versioning and Release - -CI builds and checks candidate archives on every pull request and `master` -push. `release.yml` verifies and publishes accepted archives after manual -acceptance, as described in [Release](../Reference/Release.md). - -This document owns plugin-cursor's version sources and acceptance checks. The -organization's [VERSIONING.md](https://github.com/computer-mcp/.github/blob/master/VERSIONING.md) -owns shared versioning, plugin compatibility, tags, release contents and -recovery rules. - -## Components and Version Authority - -| Shipped component | Version meaning | Authoritative source | Derived fields | Update and read-only check | -| --- | --- | --- | --- | --- | -| `cursor.zip` plugin package | Package version under the shared versioning rules | `version` in `computer-mcp-plugin.toml` | adapter `--version`, builder receipt, release tag, `release-receipt.json`, catalog entry | Edit the manifest; `Tests/test_package.py` checks the packaged adapter's `--version` | - -The archive contains the manifest, `cli-tree.json`, `bin/`, `skills/`, the README, -contribution guide, license, notices, `Documentation/` and `Examples/`. Changes -to these packaged files change the release bytes. Tests, scripts and workflows -are outside the archive. - -## Dependencies and Verified Combinations - -The package uses the Python standard library only and requires Python 3.13 or -newer on the host launch PATH. CI runs the tests on Python 3.13 and 3.14 and -checks that 3.11 and 3.12 are rejected before any vendor process starts. - -`bin/plugin_runtime.py` is copied from the organization's canonical runtime. -The `runtime` job in `ci.yml` checks it against the pinned shared workflow's -digest. Adapter and probe callers extract the native assertion from the CLI -tree with `expected_version` before calling `verify_version`. - -`computer-mcp-plugin.toml` declares the plugin API and host and architecture -compatibility. Validate host-specific requirements against the selected host -before changing the host bounds. - -`cli-tree.json` pins the exact Cursor Agent version through its -`executable_checks`, which the host applies before every CLI and adapter call. A -different vendor version requires a reviewed update of the tree, verified with -`Scripts/validate_native.py` against the real executable. - -## Derived Metadata and Drift Checks - -`Scripts/build_package.py` verifies the plugin ID, parses the CLI tree, and -produces the same archive bytes from the same source. Its receipt prints the ID, -version and SHA-256. `release.yml` calls the pinned organization release workflow -with `python3 Scripts/build_package.py` and selects the exact -`cursor-plugin-${commit}-3.13` CI artifact. The shared workflow checks the source -and manifest, rebuilds the archive and compares its bytes with that artifact. - -## Candidate, Acceptance and Publication - -The candidate is the Python 3.13 CI artifact for a reviewed `master` commit. -Run `release.yml` with `publish: false` first. Manual acceptance requires the -native version and help check with `Scripts/validate_native.py`, the ACP -initialization probe with `Scripts/probe_acp.py`, and the isolated host check -with `Scripts/validate_host.py` against the selected Computer MCP release and -the exact archive verified by the dry run. -Authenticated model execution and production installation are separate checks -and are never implied by these results. - -Record the manual results and their limits in the draft Release notes. Dispatch -`release.yml` with the accepted version tag and `publish: true` to publish. -Only a reported publication enables its dependent catalog notification job; -only that job receives the catalog secret. - -## Evidence Reuse and Invalidation - -The CI artifact name binds the source commit and Python version, and the release -receipt binds the commit, CI run, artifact digest and archive SHA-256. An archive -whose digest matches the accepted one keeps its acceptance. Any change to a -packaged file produces a new archive that needs the affected checks again. - -## Entry Points and Artifact Retention - -| Operation | Existing command or explicit manual procedure | Required access | -| --- | --- | --- | -| Version update and check | Edit `computer-mcp-plugin.toml`; `python3 -m unittest discover -s Tests -p 'test_*.py'` | Local checkout | -| Candidate validation and build | `ci.yml`; locally `python3 Scripts/build_package.py ` | CI or local checkout | -| Status and interrupted-run recovery | Inspect CI or `release.yml`; follow [Release](../Reference/Release.md#retry) | Repository Actions | -| Acceptance and publication | Manual checks and `release.yml` in [Release](../Reference/Release.md) | Signing key and release write access | -| Cleanup | Delete local output and evidence directories | Local checkout | - -The builder refuses to overwrite a different archive, and `validate_host.py` -requires a new evidence directory. Keep local build and evidence outputs under -ignored `dist/` paths and remove them after use. diff --git a/Documentation/README.md b/Documentation/README.md index 21978df..c85c9c9 100644 --- a/Documentation/README.md +++ b/Documentation/README.md @@ -1,7 +1,7 @@ # Documentation - [Architecture](Architecture/README.md): current component ownership and lifecycle. -- [Versioning and Release](Architecture/VersioningAndRelease.md): version authority, acceptance and publication rules. - [Interface](Reference/Interface.md): CLI and MCP contracts, error and retention behavior. - [Installation](Reference/Installation.md): dependencies, grants, packaging and validation. -- [Release](Reference/Release.md): publishing a release and notifying the plugin catalog. +- [Release](Reference/Release.md): version sources, compatibility, acceptance and + publication. diff --git a/Documentation/Reference/Release.md b/Documentation/Reference/Release.md index 876a81c..e59e838 100644 --- a/Documentation/Reference/Release.md +++ b/Documentation/Reference/Release.md @@ -1,16 +1,68 @@ # Release -This guide covers `release.yml` and notification of the official plugin catalog. -[Versioning and Release](../Architecture/VersioningAndRelease.md) owns this -repository's version sources and acceptance checks. The organization's -[VERSIONING.md](https://github.com/computer-mcp/.github/blob/master/VERSIONING.md) -owns shared versioning, release contents, immutability and recovery rules. +Release status: [CI](https://github.com/computer-mcp/plugin-cursor/blob/master/.github/workflows/ci.yml) +builds candidate archives on pull requests, `master` pushes and manual runs. +[`release.yml`](https://github.com/computer-mcp/plugin-cursor/blob/master/.github/workflows/release.yml) +implements dry runs and publication; native and host acceptance are manual. -The repository owner must enable GitHub release immutability before the first -release. The release workflow refuses publication unless it can verify that -setting; enabling it is a prerequisite to publishing. +The organization [VERSIONING](https://github.com/computer-mcp/.github/blob/master/VERSIONING.md) +owns version rules, including tags, version choice and the changelog. This +reference records this repository's version sources, compatibility, release +procedure and checks. The shared +[release workflow guide](https://github.com/computer-mcp/.github/blob/master/Documentation/Reference/PluginRelease.md) +describes workflow verification and recovery. -## Publish +## Components and Version Sources + +| Shipped component | Version meaning | Version source | Mirrors and derived fields | Update and read-only check | +| --- | --- | --- | --- | --- | +| `cursor.zip` plugin package | Package version | `version` in [`computer-mcp-plugin.toml`](../../computer-mcp-plugin.toml) | adapter `--version`, builder receipt, release tag, `release-receipt.json`, catalog entry | Edit the manifest; `Tests/test_package.py` checks the packaged adapter's `--version` | + +The archive contains the manifest, `cli-tree.json`, `bin/`, `skills/`, the README, +contribution guide, license, notices, `Documentation/` and `Examples/`. +Tests, build scripts and workflows are excluded from the archive. + +## Compatibility Surface + +The package contributes a file-backed CLI tree, stdio MCP adapter and Skills. +[Interface](Interface.md) owns the CLI argv and output mapping, MCP tools and +resources, session and permission semantics, retention, cancellation and errors. +The manifest owns `plugin_api` and the minimum host and architecture declarations +in `[compatibility]`. Validate changes to those bounds against the selected host. + +## Dependencies and Verified Combinations + +The package uses the Python standard library only and requires Python 3.13 or +newer on the host launch PATH. CI runs the tests on Python 3.13 and 3.14 and +checks that 3.11 and 3.12 are rejected before any vendor process starts. + +`cli-tree.json` pins the exact Cursor Agent version through its +`executable_checks`, applied before projected CLI calls and new ACP sessions. +A different vendor version requires a reviewed tree update verified with +`Scripts/validate_native.py` against the real executable. ACP initialization +uses the separate `Scripts/probe_acp.py` check. Native version/help, fixture +protocol, selected-host interoperability and authenticated execution are +separate evidence classes; see [Installation](Installation.md). + +## Derived Metadata and Drift Checks + +`Scripts/build_package.py` verifies the plugin ID, parses the CLI tree, and +produces the same archive bytes from the same source. Its builder receipt prints +the ID, version and SHA-256. The release caller passes this builder to the shared +release workflow. + +`bin/plugin_runtime.py` is copied from the organization's canonical runtime. +The `runtime` job in `ci.yml` verifies its digest against the pinned +`plugin-runtime.yml`; runtime updates and that workflow pin move together. +Adapter and probe callers extract the native assertion from the CLI tree with +`expected_version` before calling `verify_version`. + +## Candidate, Acceptance and Publication + +Publication depends on the repository's GitHub release immutability setting. +The shared workflow checks that setting before writing a Release. + +### Publish 1. Confirm that `version` in `computer-mcp-plugin.toml` has not been released and that the reviewed `master` commit has successful `ci.yml` from a `push`. @@ -27,19 +79,19 @@ setting; enabling it is a prerequisite to publishing. 4. Run the native version/help, ACP initialization and isolated host checks in [Installation](Installation.md#isolated-host-interoperability) against that exact archive. Record the manual acceptance results and their limits in the - draft Release notes. Create and push the signed annotated `vX.Y.Z` tag on - the accepted commit, and target the draft Release at that full commit SHA. + draft Release notes. Create and push the version tag that + [VERSIONING](https://github.com/computer-mcp/.github/blob/master/VERSIONING.md) requires on the accepted commit, and target the draft + Release at that full commit SHA. 5. Dispatch `release.yml` with `ref` set to that version tag and `publish: true`. The workflow verifies the tag signature and manifest version, repeats the source and archive checks, completes and verifies the draft assets, and publishes. Its dependent notifier runs only when `publish` is true and the shared workflow reports `published: true`. -The shared workflow generates the deterministic receipt and checksums under the -organization's [release contents contract](https://github.com/computer-mcp/.github/blob/master/VERSIONING.md#plugin-release-contents). -Manual acceptance evidence belongs in the Release notes. +The shared workflow generates the receipt and checksums; CI's +`package-receipt.json` remains builder metadata in the source CI artifact. -## Catalog notification +### Catalog notification `notify-catalog.yml` runs when a release is published, edited, released, unpublished or deleted, and on manual dispatch. It asks the website to reconcile @@ -64,7 +116,40 @@ job after confirmed publication. Only the notifier receives `CATALOG_APP_PRIVATE_KEY`; the reusable release workflow receives no catalog secret. Dry runs do not notify the catalog. -## Retry +## Evidence Reuse and Invalidation + +The CI artifact name identifies the source commit and Python version. The release +workflow verifies CI provenance and artifact digests; `release-receipt.json` +records the commit, CI run and attempt, artifact digest and archive SHA-256. + +An archive with the accepted digest keeps its archive acceptance for the tested +combination. Reuse of manual results is reviewed against the native dependency, +selected host, check definitions and relevant environment recorded with them. +Changes to packaged files produce a new archive and require the affected checks +again. A check-only change can reuse unchanged archive bytes with fresh affected +checks. Source tests do not replace installation, native or authenticated +execution evidence. Keep failed-check output and result limits with the manual +acceptance record. + +## Entry Points and Artifact Retention + +| Operation | Existing command or explicit manual procedure | Required access | +| --- | --- | --- | +| Version update and check | Edit `computer-mcp-plugin.toml`; `python3 -m unittest discover -s Tests -p 'test_*.py'` | Local checkout | +| Candidate validation and build | `ci.yml`; locally `python3 Scripts/build_package.py dist` | CI or local checkout | +| Native acceptance | `python3 Scripts/validate_native.py --executable `; `python3 Scripts/probe_acp.py --executable --output ` | User-installed native executable | +| Exact archive host acceptance | `python3 Scripts/validate_host.py --host --expected-host-version X.Y.Z --archive dist/cursor.zip --output `; see [Installation](Installation.md#isolated-host-interoperability) | Selected host binary and candidate archive | +| Acceptance and publication | Manual checks above; dispatch `release.yml`, dry run first | Repository Actions; publication also needs a signing key and release write access | +| Status and interrupted-run recovery | Inspect CI or `release.yml`; follow [Retry](#retry) | Repository Actions | +| Cleanup | Delete obsolete output and evidence under ignored `dist/`, and `package-receipt.json` | Local checkout | + +The builder refuses to overwrite a different archive, and `validate_host.py` +requires a new evidence directory. Remove obsolete build output before rebuilding +changed source. Keep local output and evidence under ignored `dist/`; remove +them after use unless an acceptance record requires retention. CI sets no +per-artifact retention override. + +### Retry For a failed publication, use **Re-run failed jobs**. Recovery preserves the receipt's frozen CI provenance and retains matching draft assets. Follow the