andreahlert commented on code in PR #163: URL: https://github.com/apache/airflow-steward/pull/163#discussion_r3250865872
########## docs/release-management/README.md: ########## @@ -0,0 +1,201 @@ +<!-- START doctoc generated TOC please keep comment here to allow auto update --> +<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> +**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* + +- [Release-management skill family](#release-management-skill-family) + - [Status](#status) + - [Skills](#skills) + - [Deep documentation](#deep-documentation) + - [Adopter contract](#adopter-contract) + - [Mode mapping](#mode-mapping) + - [Cross-references](#cross-references) + +<!-- END doctoc generated TOC please keep comment here to allow auto update --> + +<!-- SPDX-License-Identifier: Apache-2.0 + https://www.apache.org/licenses/LICENSE-2.0 --> + +# Release-management skill family + +End-to-end automation for an ASF project's release lifecycle, +from the planning issue and version bump through to `[ANNOUNCE]` +on `[email protected]`, archive sweep, and the per-release +audit log. Ten skills that compose into the canonical 14-step +process documented in [`process.md`](process.md). + +Why a framework skill family? Every ASF project runs essentially +the same release process: version bump, `KEYS` reconciliation, RC +signed with the Release Manager's key, staged to +`dist/apache.org/repos/dist/dev/<project>/`, voted on `dev@` per +[`release-policy.html § release approval`](https://www.apache.org/legal/release-policy.html#release-approval), +promoted to `dist/release/<project>/`, announced on +`[email protected]` per +[`release-policy.html § announcements`](https://www.apache.org/legal/release-policy.html#release-announcements), +and archived past retention per +[`release-distribution`](https://infra.apache.org/release-distribution.html). +The procedural shape is foundation-wide; the project-specific +content (release-train identity, build invocation, `KEYS` file +path, vote-window length, retention rule, audit-log location) +plugs in through [`<project-config>/`](../../projects/_template/) +just like the security family. + +Non-ASF adopters are first-class adopters of this family, not a +follow-up case. The 14-step lifecycle is described in ASF +terminology because the framework's first pilot is an ASF PMC, +but every step that touches an ASF-specific surface is implemented +as a backend call the adopter selects in +[`release-management-config.md`](../../projects/_template/release-management-config.md). +Three dimensions parametrise the lifecycle, with no ASF assumption +baked into the install path: + +- **Distribution backend** (`release_dist_backend`): `svnpubsub` + (ASF), `github-releases`, `s3`, `self-hosted`. +- **Approval mechanism** (`release_approval_mechanism`): + `dev-list-vote` (ASF), `github-discussion`, `pr-approval`, + `maintainer-roster`. +- **Announcement backend** (`release_announce_backend`): + `announce-list` (ASF), `github-release-notes`, `site-post`, + `discord-channel`. + +The 14 steps stay identical across backends; only the command set +the agent emits changes. The state-change boundaries (Drafting vs +Triage; agent never holds the signing key; agent never publishes) +stay identical too. See +[`process.md` § Adopter backends](process.md#adopter-backends) +for the full backend table and per-step mapping. + +## Status + +**Proposed.** No `release-*` skill code exists in the framework +today. This family lands as docs first (this README, the 14-step +[`process.md`](process.md), the per-skill [`spec.md`](spec.md), and +the adopter scaffold +[`projects/_template/release-management-config.md`](../../projects/_template/release-management-config.md)) +so the lifecycle, the state-change boundaries, and the adopter +contract are reviewable independently from runtime behaviour. +The skills follow in subsequent PRs, each shipped flagged +`experimental` and tracked in [`docs/modes.md`](../modes.md). This +pattern matches [Mentoring](../mentoring/README.md). + +Promotion of any skill in this family from `experimental` to +default-on, or from Drafting to a state-changing lane, requires +evidence sourced from Release Managers and binding voters that +the project's release process is healthier (fewer stalled +RCs, shorter time-to-`[ANNOUNCE]`, fewer reverted promotions), +not throughput numbers alone. The evidence window is set by +adopter governance, not by this family. + +See [`MISSION.md` § Initial Goals](../../MISSION.md#initial-goals) +for the commitment to *cut a first Apache release through the +standard process within 3 months of resolution adoption*; this +family operationalises it. + +## Skills + +The skill table below names each `release-*` skill, its mode, and +the lifecycle step(s) it owns. Read [`spec.md`](spec.md) for the +per-skill state-change boundary; read [`process.md`](process.md) +for the step it executes against. + +| Skill | Mode | Steps owned | Purpose | +|---|---|---|---| +| `release-prepare` | Drafting | 1, 2, 14 | Open the planning issue, draft the version-bump + changelog + NOTICE/LICENSE PR, then draft the post-release `-SNAPSHOT` bump. | +| `release-keys-sync` | Drafting | 3 | Draft the `KEYS` diff for a Release Manager cutting their first release for the project. Agent never holds the private key. | +| `release-rc-cut` | Drafting | 4, 5 | Emit the paste-ready command sequence, signed tag, build, detached signatures, checksums, `svn` import to `dist/dev/<project>/`. Agent never signs and never imports. | +| `release-verify-rc` | Triage / Pairing | 6 | Read-only pre-flight: signatures against the project's `KEYS`, checksums, license headers (Apache RAT), NOTICE/LICENSE presence, no prohibited binaries, version-string consistency. Voters can run it in their own dev loop before posting `+1`. | +| `release-vote-draft` | Drafting | 7 | Draft the `[VOTE]` email body to `dev@<project>`. Agent never sends. | +| `release-vote-tally` | Triage | 9 | Parse the vote thread, classify each reply (+1 / 0 / -1) binding vs non-binding against the PMC roster, propose `[RESULT] [VOTE]`. Conservative on ambiguous votes, refuses to count, flags `AMBIGUOUS, needs RM call`. | +| `release-promote` | Drafting | 10 | Emit the paste-ready `svn mv dist/dev → dist/release` command set plus commit message. Agent never moves; the human commit is the act of release. | +| `release-announce-draft` | Drafting | 11 | Draft the `[ANNOUNCE]` email body to `[email protected]` and the site-bump PR (download page, release notes, version banner). Agent never sends mail and never merges the site PR. | +| `release-archive-sweep` | Triage | 12 | Scan `dist/release/<project>/`, identify releases past retention, propose the `svn mv` sequence to `archive.apache.org`. Agent never moves. | +| `release-audit-report` | Triage (dashboard) | 13 | Read-only structured report per release, RM, voters with binding flags, artefacts with sigs and checksums, promotion revision, `[ANNOUNCE]` archive URL. Output appended to the project's audit log. | + +Two non-negotiable boundaries cross every Drafting skill above: + +- **The agent never holds, invokes, or proxies the Release Review Comment: Right — the boundary is already structurally enforced by the sandbox; the doc treats it as policy when it's actually mechanism. I'll rewrite the two bullets to name the isolation framework as the implementation: the agent runs without credentials, hits `svn commit`, the sandbox detects the escape, the RM authorises that specific command outside the sandbox, and the agent never sees the key material. The policy statement stays above it as the invariant the mechanism enforces, so adopters who plug in a different sandbox still have to satisfy the same boundary. I'll cross-link to [`secure-agent-setup.md` § sandbox-bypass-visibility-hook](https://github.com/apache/airflow-steward/blob/main/docs/setup/secure-agent-setup.md#sandbox-bypass-visibility-hook), which is the per-call approval gate this relies on. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
