andreahlert commented on code in PR #163: URL: https://github.com/apache/airflow-steward/pull/163#discussion_r3265956597
########## docs/release-management/process.md: ########## @@ -0,0 +1,521 @@ +<!-- 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 workflow: process and label lifecycle](#release-management-workflow-process-and-label-lifecycle) + - [Adopter backends](#adopter-backends) + - [Process reference: the 14 steps](#process-reference-the-14-steps) + - [Step 1: Release planning + version bump](#step-1-release-planning--version-bump) + - [Step 2: Changelog, NOTICE, LICENSE](#step-2-changelog-notice-license) + - [Step 3: `KEYS` reconciliation](#step-3-keys-reconciliation) + - [Step 4: Cut the release candidate](#step-4-cut-the-release-candidate) + - [Step 5: Stage to `dist/dev/`](#step-5-stage-to-distdev) + - [Step 6: Pre-flight RC verification](#step-6-pre-flight-rc-verification) + - [Step 7: `[VOTE]` thread on `dev@`](#step-7-vote-thread-on-dev) + - [Step 8: Voting window](#step-8-voting-window) + - [Step 9: Tally + `[RESULT] [VOTE]`](#step-9-tally--result-vote) + - [Step 10: Promote `dist/dev/` to `dist/release/`](#step-10-promote-distdev-to-distrelease) + - [Step 11: `[ANNOUNCE]` + site bump](#step-11-announce--site-bump) + - [Step 12: Archive sweep](#step-12-archive-sweep) + - [Step 13: Audit log](#step-13-audit-log) + - [Step 14: Post-release version bump](#step-14-post-release-version-bump) + - [Label lifecycle](#label-lifecycle) + - [State diagram](#state-diagram) + - [Label reference](#label-reference) + - [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 workflow: process and label lifecycle + +The authoritative reference for the 14-step release lifecycle and +the label-lifecycle state diagram the [release-management +skills](../../.claude/skills/) execute against. The +[family README](README.md) lists the skills; this document is the +process they share. The [spec](spec.md) defines per-skill scope, +state-change boundary, and adopter knobs. + +The lifecycle is described in **ASF terminology by default** +(svnpubsub on `dist.apache.org`, `[VOTE]` on `dev@`, `[ANNOUNCE]` +on `[email protected]`), because the framework's first pilots +include an ASF PMC release. 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), +not a hard-coded operation. Non-ASF adopters resolve the same +abstract step to their own backend; see the +[Adopter backends](#adopter-backends) section for the dimensions +and the per-step backend mapping. + +## Adopter backends + +Three dimensions parametrise the lifecycle. Each adopter picks one +value per dimension in `release-management-config.md`. The 14 +steps stay identical; only the backend the agent emits commands +against changes. + +| Dimension | Config key | ASF default | Non-ASF examples | +|---|---|---|---| +| Distribution backend | `release_dist_backend` | `svnpubsub` (`svn import` to `dist/dev/`, `svn mv` to `dist/release/`) | `github-releases` (`gh release upload` / `gh release edit --draft=false`), `s3` (`aws s3 cp` / `aws s3 mv`), `self-hosted` (project-supplied command template) | +| Approval mechanism | `release_approval_mechanism` | `dev-list-vote` (`[VOTE]` thread on `dev@<project>.apache.org`, 72h window, 3 binding +1, more +1 than -1) | `github-discussion` (named Discussion thread on `<upstream>` repo), `pr-approval` (a "release-NN" PR with approvals from the configured roster), `maintainer-roster` (signed approvals from a named roster file) | +| Announcement backend | `release_announce_backend` | `announce-list` (mail to `[email protected]`, cc `dev@`, `users@`) | `github-release-notes` (the release-page body is the announcement), `site-post` (a blog post in `site_repo`), `discord-channel` (a webhook into a named channel) | + +Each `release-*` skill consults the relevant key and emits +backend-shaped paste-ready commands. The state-change boundaries +([spec § Cross-cutting commitments](spec.md#cross-cutting-commitments)) +do not change: the agent still emits a recipe; the human still +runs it. Swapping `svn` for `gh release upload` swaps the +backend, not the boundary. + +The vote-tally roster (`release-vote-tally`) reads from the +adopter's `pmc-roster.md` for ASF projects, or +`<release_approver_roster_path>` (typically +`<project-config>/release-approvers.md`) for non-ASF adopters; both +files share the same schema (handle, binding-flag, optional GPG +fingerprint). + +> [!IMPORTANT] +> Release Management is **proposed** in the framework today. No +> `release-*` skill code exists yet. This document, the family +> [`README.md`](README.md), the [`spec.md`](spec.md), and +> [`projects/_template/release-management-config.md`](../../projects/_template/release-management-config.md) +> land first so the lifecycle, the state-change boundaries, and the +> adopter contract are reviewable independently from the runtime +> behaviour. The pattern matches [Mentoring](../mentoring/spec.md). +> See [`docs/modes.md` § Drafting / Triage](../modes.md#drafting) +> for status. + +## Process reference: the 14 steps + +This is the authoritative outline of the 14-step lifecycle. Each +step links to the skill that owns it (or marks it `proposed` if the +skill is not yet implemented). The brief descriptions below are an +overview, not a substitute for the linked skill's `SKILL.md`. + +Two non-negotiable boundaries cross the lifecycle: + +- **The agent never holds, invokes, or proxies the Release + Manager's private signing key.** Any step that needs a signature + emits a paste-ready command sequence; the RM runs it on their own + machine, as themselves. This mirrors the + [`security-cve-allocate`](../../.claude/skills/security-cve-allocate/SKILL.md) + pattern (Vulnogram URL + paste-ready JSON, human submits) and + satisfies [RFC-AI-0004 Principle 1](../rfcs/RFC-AI-0004.md#principle-1--human-in-the-loop-on-every-state-change). +- **The agent never publishes the release.** Steps 10 + (`svn mv dist/dev → dist/release`) and 11 (`[ANNOUNCE]` send, + site bump merge) are the moments of release; the agent drafts + artefacts, the RM and the PMC execute and merge. + +```mermaid +flowchart TD + S1[1. Plan + version bump] + S2[2. Changelog + NOTICE/LICENSE] + S3[3. KEYS reconciliation] + S4[4. Cut RC: tag + build + sign] + S5[5. Stage to dist/dev] + S6[6. Pre-flight verify] + S7[7. VOTE thread on dev@] + S8[8. Voting window] + S9{9. Tally: pass or fail?} + FAIL([Fail: revert RC, return to step 4]) + S10[10. Promote dist/dev to dist/release] + S11[11. ANNOUNCE + site bump] + S12[12. Archive sweep] + S13[13. Audit log] + S14[14. Post-release version bump] + + S1 --> S2 + S2 --> S3 + S3 --> S4 + S4 --> S5 + S5 --> S6 + S6 --> S7 + S7 --> S8 + S8 --> S9 + S9 -->|pass| S10 + S9 -->|fail| FAIL + FAIL --> S4 + S10 --> S11 + S11 --> S12 + S11 --> S14 + S12 --> S13 + S14 --> S13 + + classDef prep fill:#fff3cd,stroke:#664d03,color:#000 + classDef rc fill:#cfe2ff,stroke:#055160,color:#000 + classDef vote fill:#e2d9f3,stroke:#3d2a6b,color:#000 + classDef publish fill:#d4edda,stroke:#0f5132,color:#000 + classDef terminal fill:#f8d7da,stroke:#842029,color:#000 + + class S1,S2,S3 prep + class S4,S5,S6 rc + class S7,S8,S9 vote + class S10,S11,S12,S13,S14 publish + class FAIL terminal +``` + +Colour key: yellow = preparation, blue = release candidate, purple = +vote, green = publication and follow-up. + +### Step 1: Release planning + version bump + +**Owner:** PMC + nominated Release Manager (RM). +**Skill:** `release-prepare` +*(proposed)*, Drafting. + +The RM opens a planning issue listing the target version, the +release train it belongs to (see +[`<project-config>/release-trains.md`](../../projects/_template/release-trains.md)), +the cut-off commit, and the issues / PRs in scope. The skill drafts +that planning issue from the configured release-train metadata, then +drafts the version-bump PR (e.g. `pom.xml`, `pyproject.toml`, +`Cargo.toml`, `setup.py`, package manifests). The PR remains in +draft until the RM marks it ready; the agent never marks ready, never +merges. + +For non-ASF adopters with no release-train concept the planning step +collapses to a tag-and-PR pair; the skill detects the absence of +[`<project-config>/release-trains.md`](../../projects/_template/release-trains.md) +and adapts. + +### Step 2: Changelog, NOTICE, LICENSE + +**Owner:** RM. +**Skill:** `release-prepare` +*(proposed)*, Drafting (same skill as Step 1, second invocation). + +The skill drafts the changelog entry from the merged-PR set since +the previous release tag, the `NOTICE` diff (third-party +attributions added or removed), and the `LICENSE` diff if any +license-categorised dependency changed +([ASF Category-A/B/X policy](https://www.apache.org/legal/resolved.html)). +The skill flags any Category-X dependency for the RM to remove before +the cut and refuses to advance the planning issue until that flag +clears. + +Output: a single PR proposed against the release branch, RM merges +after their own review. + +### Step 3: `KEYS` reconciliation + +**Owner:** RM. +**Skill:** `release-keys-sync` +*(proposed)*, Drafting. + +If the RM is signing their first release for the project, their +public key must appear in the project's `KEYS` file under +`dist/release/<project>/KEYS`. The skill drafts the `KEYS` diff +(public-key block appended in the project's existing format), +emits the `svn` command sequence to commit it, and reminds the RM +that the key must also be uploaded to a public keyserver per +[the ASF release-signing FAQ](https://infra.apache.org/release-signing.html). +The agent never holds the private key and never runs `svn commit`; +the RM executes both as themselves. + +If the RM's key is already present and unchanged, the skill is a +no-op and reports so on the planning issue. + +### Step 4: Cut the release candidate + +**Owner:** RM. +**Skill:** `release-rc-cut` +*(proposed)*, Drafting. + +The skill emits a paste-ready command sequence: + +1. `git tag -s <version>-rcN -m "..."` (signed tag, RM's key). +2. Build invocation, project-specific + (`<project-config>/release-build.md`). +3. `gpg --detach-sign --armor <artefact>` for each artefact. +4. `sha512sum <artefact> > <artefact>.sha512` for each artefact. + +The skill writes nothing to disk and runs nothing locally. The RM +runs every command on their own machine, with their own key, in +their own checkout. The skill's output is the *recipe*; correctness +of the recipe is reviewable independently from execution. After the +RM reports back the artefact list + checksums + sig filenames, the +skill records them in the planning issue's audit-trail comment for +Step 13. + +> [!NOTE] +> Detached `.asc` signatures and `.sha512` checksums are the ASF +> baseline; some projects also publish `.sha256` for older +> downstream tools. The skill reads +> [`<project-config>/release-build.md`](../../projects/_template/release-build.md) +> to determine which digests apply. + +### Step 5: Stage to `dist/dev/` Review Comment: Thank you, my mistake! Agreed, important one. a voter treating a clean release-verify-rc report as their +1 is exactly the failure the framework is built against. added a disclaimer to the spec, the report doesn't discharge the voter's obligation to download, compile, and test on their own hardware. -- 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]
