From ec3a776df302456224c71bd628e74d6f2df78cbe Mon Sep 17 00:00:00 2001 From: Justin McLean Date: Mon, 3 Aug 2026 06:03:19 +0000 Subject: [PATCH] docs: reflect the shipped 0.1.0 release in adoption docs 0.1.0 is released (promoted to dist/release/magpie/0.1.0), so the adoption docs no longer match reality: - README + install-recipes: svn-zip is the recommended production path rather than "forthcoming"; git-branch is no longer "the default during the framework's pre-release phase". - install-recipes Method 1 fetched apache-magpie--source-release.zip, which is not the artefact name that shipped. Every other doc in the tree says -source.zip, so the recipe as written 404s. - install-recipes Method 1 templated a adopter dist subdirectory. Magpie has its own dist area now, so hard-code it and split DIST_BASE (KEYS at the project root) from REL_BASE (artefacts under the per-version subdirectory). - README cross-reference still called MISSION.md a draft proposal; it was adopted by Board resolution on 17 June 2026, and the NOTE block earlier in the README already says so. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01KNKkaL6zyzcnyD746GKJg5 --- README.md | 8 ++++---- docs/setup/install-recipes.md | 34 +++++++++++++++++----------------- 2 files changed, 21 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 6e0566ca..fa7dafca 100644 --- a/README.md +++ b/README.md @@ -98,9 +98,9 @@ Pick an install method and follow the verbatim recipe in | Method | When to use | Reproducibility | |---|---|---| -| `svn-zip` | Production once ASF official releases ship to `dist.apache.org` (signed + checksummed) | Frozen by version | -| `git-tag` | Pin a specific framework version | Frozen by tag | -| `git-branch` (default `main`) | WIP path — track the framework's `main` directly for the latest unreleased changes. | Tracks tip | +| `svn-zip` (**recommended**) | Production. Signed + checksummed zip from `dist.apache.org`; `0.1.0` is the current release. | Frozen by version | +| `git-tag` | Pin a version without going through the signed zip (e.g. testing a release candidate). | Frozen by tag | +| `git-branch` (`main`) | WIP path — track the framework's `main` directly for the latest unreleased changes. | Tracks tip | Each recipe is a single shell block that: @@ -235,7 +235,7 @@ files are reproduced in [`NOTICE`](NOTICE). ## Cross-references -- [`MISSION.md`](MISSION.md) — **draft** project-establishment proposal: motivation, scope, design commitments, initial PMC composition target. +- [`MISSION.md`](MISSION.md) — the project's founding mission and design commitments, as filed in the establishment proposal adopted by the Board on 17 June 2026: motivation, scope, initial PMC composition target. - [`docs/setup/agentic-overrides.md`](docs/setup/agentic-overrides.md) — the contract between adopters who write overrides and framework skills that read them. - [`docs/prerequisites.md`](docs/prerequisites.md) — what a maintainer needs installed before invoking any framework skill (Claude Code, Gmail MCP, GitHub auth, browser, `uv`, etc.). - [`docs/source-release-contents.md`](docs/source-release-contents.md) — what ships in the signed `apache-magpie--source.zip` (and what is excluded), with the rationale for the repository-root metadata/config files it keeps. diff --git a/docs/setup/install-recipes.md b/docs/setup/install-recipes.md index 095af580..d3e225b9 100644 --- a/docs/setup/install-recipes.md +++ b/docs/setup/install-recipes.md @@ -31,9 +31,9 @@ Pick the recipe that matches your distribution preference: | Method | When to use | Reproducibility | |---|---|---| -| [**svn-zip**](#method-1--released-zip-from-asf-distribution) | Production adopters once the framework ships official ASF releases. Signed + checksummed. | Frozen by version | +| [**svn-zip**](#method-1--released-zip-from-asf-distribution) | **Recommended for production adopters.** Signed + checksummed zip from the ASF distribution area; `0.1.0` is the current release. | Frozen by version | | [**git-tag**](#method-2--git-tag) | Pinning a specific framework version (e.g. for testing a release candidate, or for a cautious adopter who tracks named releases only). | Frozen by tag | -| [**git-branch**](#method-3--git-branch-defaults-to-main) | WIP path — track the framework's `main` branch directly. The default during the framework's pre-release phase. | Tracks branch tip | +| [**git-branch**](#method-3--git-branch-defaults-to-main) | WIP path — track the framework's `main` branch directly for the latest unreleased changes. | Tracks branch tip | > **Canonical layout — no per-project convention to pick.** > `.agents/skills/` is the one canonical home (see @@ -54,33 +54,33 @@ Pick the recipe that matches your distribution preference: ## Method 1 — released zip from ASF distribution -> **Status: forthcoming.** ASF release distribution -> (`https://dist.apache.org/repos/dist/release//`) +> **Status: recommended.** ASF release distribution +> (`https://dist.apache.org/repos/dist/release/magpie/`) > is the canonical home for ASF-blessed releases per the > [release-policy](https://www.apache.org/legal/release-policy.html) > and [infra release-distribution guidelines](https://infra.apache.org/release-distribution.html). -> This recipe will be the recommended path once the framework -> ships its first official release; until then, use -> [Method 3 — git-branch](#method-3--git-branch-defaults-to-main). +> Magpie ships there from `0.1.0` onwards, so this is the path +> production adopters should take. ```bash # === Magpie bootstrap — Method 1: signed zip from ASF dist === -# Replace with the host adopter's ASF dist subdirectory -# (e.g. `airflow` once releases land at -# https://dist.apache.org/repos/dist/release/airflow/). -# Replace with the framework version you want. +# Replace with the framework version you want (e.g. 0.1.0). +# Released versions are listed at +# https://dist.apache.org/repos/dist/release/magpie/ cd /path/to/your/repo VERSION= -PROJECT= -DIST_BASE=https://dist.apache.org/repos/dist/release/${PROJECT} -ZIP=apache-magpie-${VERSION}-source-release.zip +# KEYS lives at the project root of the dist area; the artefacts live +# under a per-version subdirectory. +DIST_BASE=https://dist.apache.org/repos/dist/release/magpie +REL_BASE=${DIST_BASE}/${VERSION} +ZIP=apache-magpie-${VERSION}-source.zip # 1. Download zip + signature + checksum, verify, extract to .apache-magpie/ -curl -fsSLO ${DIST_BASE}/${ZIP} -curl -fsSLO ${DIST_BASE}/${ZIP}.sha512 -curl -fsSLO ${DIST_BASE}/${ZIP}.asc +curl -fsSLO ${REL_BASE}/${ZIP} +curl -fsSLO ${REL_BASE}/${ZIP}.sha512 +curl -fsSLO ${REL_BASE}/${ZIP}.asc sha512sum -c ${ZIP}.sha512 # Optional but recommended — verify the OpenPGP signature against the # project KEYS file (see https://infra.apache.org/release-signing.html):