justinmclean commented on code in PR #163: URL: https://github.com/apache/airflow-steward/pull/163#discussion_r3252593468
########## 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 Review Comment: Steps 12, 13, and 14 are described as post-promote follow-ups. The flowchart has both S11 → S12 and S11 → S14, implying 12 and 14 are parallel paths. But the narrative says Step 14 (post-release snapshot bump) is logically after Step 11, while Step 12 (archive sweep) is separate. Worth clarifying with a note or re-examining whether 12→13 and 14→13 should be separate terminal paths. -- 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]
