From 4dddc9d11ceaa3b3de7770426bce2cd26f93ed7a Mon Sep 17 00:00:00 2001 From: showxu <10173746+showxu@users.noreply.github.com> Date: Thu, 22 Oct 2026 12:42:36 +0800 Subject: [PATCH] docs: move release facts to the release reference --- AGENTS.md | 4 +- Documentation/Architecture/Documentation.md | 7 +- Documentation/Architecture/README.md | 3 +- .../Architecture/VersioningAndRelease.md | 81 ------------ Documentation/README.md | 4 +- Documentation/Reference/Release.md | 119 +++++++++++++++--- 6 files changed, 115 insertions(+), 103 deletions(-) delete mode 100644 Documentation/Architecture/VersioningAndRelease.md diff --git a/AGENTS.md b/AGENTS.md index 25af9a1..d38a09b 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/Documentation.md b/Documentation/Architecture/Documentation.md index 584494f..871f8fc 100644 --- a/Documentation/Architecture/Documentation.md +++ b/Documentation/Architecture/Documentation.md @@ -6,9 +6,10 @@ CONTRIBUTING.md describes contributor checks. Current package facts belong in Documentation/Architecture/Package.md; commands, formats and operating detail belong in Documentation/Reference/. -Version and release rules belong in -Documentation/Architecture/VersioningAndRelease.md. Durable transitions or -accepted decisions may have separate history records when needed. +Version rules belong in the +[organization VERSIONING](https://github.com/computer-mcp/.github/blob/master/VERSIONING.md). +[Release](../Reference/Release.md) owns release facts and procedure. Durable +transitions or accepted decisions may have separate history records when needed. GitHub-specific configuration belongs in .github/. The SwiftPM products are executables. Their user-facing interface is the CLI/MCP contract, documented in the manual and reference pages. There is no public library API or DocC catalog. Any future public library API needs a catalog beside its owning target; generated .doccarchive output remains a build artifact. diff --git a/Documentation/Architecture/README.md b/Documentation/Architecture/README.md index 0e2315b..fdb1d40 100644 --- a/Documentation/Architecture/README.md +++ b/Documentation/Architecture/README.md @@ -2,5 +2,4 @@ [Package](Package.md) describes the current components, dependencies and ownership boundaries. [Documentation](Documentation.md) describes repository documentation -roles and the API documentation scope. [Versioning and Release](VersioningAndRelease.md) -defines version authority, acceptance and publication. +roles and the API documentation scope. diff --git a/Documentation/Architecture/VersioningAndRelease.md b/Documentation/Architecture/VersioningAndRelease.md deleted file mode 100644 index d3b841a..0000000 --- a/Documentation/Architecture/VersioningAndRelease.md +++ /dev/null @@ -1,81 +0,0 @@ -# Versioning and Release - -The organization's [VERSIONING.md](https://github.com/computer-mcp/.github/blob/master/VERSIONING.md) -owns shared version rules, plugin API and host-version compatibility, dependency -requirements, tags, release contents and immutability. This document owns the -plugin-swift-format version sources, package boundaries and acceptance checks. -The [release guide](../Reference/Release.md) describes the operator procedure. - -## Components and Version Authority - -| Shipped component | Version meaning | Authoritative source | Derived fields | Update and read-only check | -| --- | --- | --- | --- | --- | -| `swift-format.zip` plugin package | Package version | `version` in `computer-mcp-plugin.toml` | builder and release receipts, tag `vX.Y.Z`, catalog entry | Edit the manifest; `release.yml` verifies agreement with the tag | - -The `export-swift-format-tree` executable is a maintainer tool that regenerates -`cli-tree.json`. It is not shipped and has no version of its own. - -The archive contains the manifest, `cli-tree.json`, the README, contribution -guide, license, notices, `ThirdPartyNotices/` and `Documentation/`. Changes to -these files change the archive. The exporter, tests, scripts and workflows are -not packaged. - -## Dependencies and Verified Combinations - -`cli-tree.json` pins the formatter through its `executable_checks`: the -`--version` output and the SHA-256 of the `--experimental-dump-help` output. The -host applies them before every call. A different formatter requires regenerating -the tree with the exporter and a reviewed package update. - -`computer-mcp-plugin.toml` declares the plugin API and host-version constraints -under the organization's compatibility rules. - -The exporter depends on swift-argument-parser, locked in `Package.resolved`. CI -resolves packages and fails if the lockfile changes. The package builder needs -only the Python 3.11 standard library; CI runs its tests and build on Python -3.11 and 3.13. - -## Derived Metadata and Drift Checks - -`Scripts/build_package.py` verifies the plugin ID, parses the CLI tree, skips -hidden files and Python caches, rejects links and special files, and produces -the same archive bytes from the same source. The exporter's Swift tests cover -tree generation from recorded native help. The builder receipt prints the ID, -version and SHA-256. - -## Candidate, Acceptance and Publication - -The candidate is `swift-format-plugin-` from a successful `ci.yml` push -run for a reviewed `master` commit. It contains `swift-format.zip` and the -builder's `package-receipt.json`. - -`release.yml` calls the organization's pinned reusable release workflow with -`python3 Scripts/build_package.py` and that exact CI artifact name. The workflow -rebuilds and compares the archive bytes. Manual acceptance validates and -installs the verified archive with the selected Computer MCP host, binds the -supported formatter, and exercises format and lint calls. Record those results -and their limits in the draft Release notes before publication. - -The release caller invokes `notify-catalog.yml` only when publication was -requested and the reusable workflow reports `published`. Only that notification -job receives the catalog App private key. - -## Evidence Reuse and Invalidation - -The CI artifact name binds the source commit, and the builder receipt binds the -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 the commands in [CONTRIBUTING](../../CONTRIBUTING.md) | CI or local checkout | -| Release verification and publication | `release.yml`; dry run and acceptance steps in [Release](../Reference/Release.md) | Repository Actions; signing key for the version tag | -| Status and interrupted-run recovery | Rerun failed jobs; shared recovery rules in [VERSIONING.md](https://github.com/computer-mcp/.github/blob/master/VERSIONING.md#plugin-release-contents) | Repository Actions | -| Cleanup | Delete local output directories and `.build/` | Local checkout | - -CI keeps candidate artifacts for 14 days. The builder refuses to overwrite a -different archive. Local package outputs belong in ignored `dist/`. diff --git a/Documentation/README.md b/Documentation/README.md index f5a9ead..29034f1 100644 --- a/Documentation/README.md +++ b/Documentation/README.md @@ -1,7 +1,7 @@ # Documentation - [Architecture](Architecture/README.md): exporter, native CLI and host boundaries. -- [Versioning and Release](Architecture/VersioningAndRelease.md): version authority, acceptance and publication rules. - [Interface](Reference/Interface.md): source provenance, argument mapping and coverage. -- [Release](Reference/Release.md): publishing a release and notifying the plugin catalog. +- [Release](Reference/Release.md): version sources, compatibility, acceptance and + publication. - [Root manual](../README.md): setup, tool usage, generation and testing. diff --git a/Documentation/Reference/Release.md b/Documentation/Reference/Release.md index bf654a0..c4782ae 100644 --- a/Documentation/Reference/Release.md +++ b/Documentation/Reference/Release.md @@ -1,19 +1,78 @@ # Release -This guide covers releasing through `.github/workflows/release.yml` and -notifying 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 version, release-content and immutability rules; its +Release status: [CI](https://github.com/computer-mcp/plugin-swift-format/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-swift-format/blob/master/.github/workflows/release.yml) +implements dry runs and publication; native and host acceptance are manual. + +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 verification, receipts and recovery. +describes workflow verification and recovery. -Before the first release, the repository owner must enable GitHub release -immutability in the repository settings. The release workflow refuses -publication if that prerequisite is disabled or cannot be verified. +## Components and Version Sources -## Publish +| Shipped component | Version meaning | Version source | Mirrors and derived fields | Update and read-only check | +| --- | --- | --- | --- | --- | +| `swift-format.zip` plugin package | Package version | `version` in [`computer-mcp-plugin.toml`](../../computer-mcp-plugin.toml) | builder and release receipts, release tag, catalog entry | Edit the manifest; `release.yml` checks agreement with the tag | + +The `export-swift-format-tree` executable is a maintainer tool that regenerates +`cli-tree.json`. It is not shipped and has no version of its own. + +The archive contains the manifest, `cli-tree.json`, the README, contribution +guide, license, notices, `ThirdPartyNotices/` and `Documentation/`. +The exporter, tests, build scripts and workflows are excluded from the archive. + +## Compatibility Surface + +The package contributes the CLI tree consumed by the host's generic CLI runtime. +[Interface](Interface.md) owns command coverage, argument and stdin mapping, +output behavior and executable checks. The manifest owns `plugin_api` and +host-version constraints. + +For the maintainer exporter, [`Package.swift`](https://github.com/computer-mcp/plugin-swift-format/blob/master/Package.swift) declares +the Swift tools version and macOS deployment floor. Its command options, +generated tree and structured errors are exercised by the Swift tests. + +## Dependencies and Verified Combinations + +`cli-tree.json` pins the formatter through its `executable_checks`: the +`--version` output and the SHA-256 of the `--experimental-dump-help` output. +The host applies them before every authorized call. A different formatter +requires regenerating the tree with the exporter and a reviewed package update. + +The exporter depends on swift-argument-parser. `Package.swift` declares its +lower bound and next-major compatibility range; +[`Package.resolved`](https://github.com/computer-mcp/plugin-swift-format/blob/master/Package.resolved) records the selected version and +revision. CI resolves packages and fails if the lockfile changes. The formatter +baseline is independent of the exporter's SwiftPM dependency version. + +The package builder needs only the Python 3.11 standard library; CI runs its +tests and build on Python 3.11 and 3.13. Swift tests use recorded native help; +host installation and real format/lint calls are separate manual acceptance. + +## Derived Metadata and Drift Checks + +`Scripts/build_package.py` verifies the plugin ID, parses the CLI tree, skips +hidden files and Python caches, rejects links and special files, and produces +the same archive bytes from the same source. The builder receipt prints the ID, +version and SHA-256. + +The exporter regenerates `cli-tree.json` from verified native input; the +generation command is in [the manual](../../README.md#regenerate-and-test). +Its Swift tests cover generation from recorded help. CI checks the SwiftPM +lockfile, strict Swift formatting, Swift tests and a release exporter build +before running the Python package checks; [CONTRIBUTING](../../CONTRIBUTING.md#validation) +lists those commands. + +## 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 a successful `ci.yml` push run. @@ -28,7 +87,7 @@ publication if that prerequisite is disabled or cannot be verified. 3. Validate and install that exact archive with the selected Computer MCP host, bind the supported `swift-format`, and run a format and a lint call. The tree's executable checks reject any other formatter version or interface. -4. Create a signed annotated tag `vX.Y.Z` on the accepted commit and push it. +4. Create the version tag that [VERSIONING](https://github.com/computer-mcp/.github/blob/master/VERSIONING.md) requires on the accepted commit and push it. Create a draft Release for that tag targeting the full commit SHA. Record the archive SHA-256, host and formatter versions, manual acceptance results and their limits in its release notes. @@ -43,7 +102,7 @@ The Release assets are `swift-format.zip`, `release-receipt.json` and not a Release asset. A dry run performs verification and assembly without writing a Release or receiving catalog credentials. -## 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 @@ -67,7 +126,39 @@ release-event workflows. `release.yml` calls `notify-catalog.yml` as a dependent job after confirmed publication. Only this notification job receives the catalog secret; the reusable release workflow receives no secrets. -## Retry +## Evidence Reuse and Invalidation + +The CI artifact name identifies the source commit, and the builder receipt records +the archive SHA-256. 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 the commands in [CONTRIBUTING](../../CONTRIBUTING.md#validation), then `python3 Scripts/build_package.py dist` | CI or local checkout with Swift toolchain and resolved dependencies | +| Native and host acceptance | Validate and install the exact archive with the selected host, bind the supported formatter and exercise format/lint calls | Selected host, formatter and authorized workspace | +| 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 local output directories and reproducible `.build/` products | Local checkout | + +CI keeps candidate artifacts for 14 days. The builder refuses to overwrite a +different archive. Local package output belongs in ignored `dist/`; remove +output and reproducible caches after use unless an acceptance record requires +retention. + +### Retry For a failed release run, use **Re-run failed jobs**. The shared workflow's [recovery procedure](https://github.com/computer-mcp/.github/blob/master/Documentation/Reference/PluginRelease.md#run-and-recover)