feat(release-management): propose family with 14-step lifecycle and non-ASF backend abstraction

[andreahlert]

Summary

Propose the release-management skill family docs-first, mirroring the Mentoring precedent (spec before code). Ten release-* skills compose the canonical 14-step ASF release lifecycle, from planning issue and version bump through [ANNOUNCE], archive sweep, and per-release audit log. The family lands as docs only in this PR; the skills follow flagged experimental in subsequent PRs.

Non-ASF adopters are first-class. Three backend switches parametrise distribution (svnpubsub | github-releases | s3 | self-hosted), approval (dev-list-vote | github-discussion | pr-approval | maintainer-roster), and announcement (announce-list | github-release-notes | site-post | discord-channel). The 14 steps stay identical across backends; only the command set the agent emits changes. ASF TLPs are pinned to dev-list-vote and announce-list per release-policy.html.

Two non-negotiable state-change boundaries cross every Drafting skill:

• Agent never holds, invokes, or proxies the Release Manager's private signing key. Steps 3, 4, 10 emit paste-ready recipes; the RM signs and runs svn commit as themselves.
• Agent never publishes. Steps 10 (svn mv dist/dev → dist/release) and 11 ([ANNOUNCE] send, site bump merge) are the moments of release; the human commit is the act of release.

Mirrors security-cve-allocate (Vulnogram URL + paste-ready JSON, human submits) and satisfies RFC-AI-0004 Principle 1.

What lands

• docs/release-management/README.md, family overview, skill table, state-change boundaries
• docs/release-management/process.md, 14-step lifecycle with Mermaid flowchart, per-step description, label state diagram, Adopter backends table
• docs/release-management/spec.md, per-skill scope, state-change boundary, hand-off protocol, adopter contract
• projects/_template/release-management-config.md, family-wide adopter contract with the 3 backend switches
• projects/_template/release-build.md, build invocation, digest set, binary-exclude rules
• projects/_template/pmc-roster.md, roster used by release-vote-tally to classify binding vs non-binding
• projects/_template/site-repo.md, site-bump PR target for release-announce-draft
• Wires the family into README.md (root) and docs/modes.md under Triage + Drafting subsections, each row marked proposed

Operationalises the MISSION.md § Initial Goals commitment to cut a first Apache release through the standard process within 3 months of resolution adoption, with non-ASF adopters served from day one.

Status

Proposed. No release-* skill code in this PR. Promotion of any skill 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.

Test plan

• prek run --all-files green (markdownlint, typos, doctoc, end-of-file, trailing whitespace)
• lychee --offline green across the 7 new + 2 modified files
• doctoc TOCs reflect current H2/H3 structure on all 4 docs files + 4 scaffolds
• Cross-references between process.md, spec.md, README.md, and projects/_template/release-management-config.md resolve
• docs/modes.md rows match the skill table in README.md
• Adopter contract required-keys list in spec.md matches the keys actually defined in projects/_template/release-management-config.md
• Non-ASF backend switches in process.md § Adopter backends align with the switches block in release-management-config.md § Backends
• ASF state-change boundaries (key, publication, mail, labels) consistent between spec.md and the Drafting-row purposes in README.md

[choo121600]

Wow...! this is huge 😄
Overall this looks really good to me.

I’d especially love to hear feedback from people who have deep ASF release-management experience, since this touches a lot of important release-process and policy boundaries.

[potiuk]

On it.. That one looks really cool !

[potiuk]

Fantastic! I reviewed it in detail and I have two comments only - to better integrate with existing manual release processes and handle the fact that most ASF PMCs already have good and followable release documentation - I think specific project configuration and overrides should be "synced" with such manual docuementation - we do not want to "completely" replace release process with agentic flows, there needs to be a manual one, that will be easier to follow without steward. Some release managers might not want to use agents, and might choose to follow manual path - but if we actually encode the rule that we also have to have - pure manually followed way of release - this will 100% alleviate those concerns. And actually - very funny - it will allow those release managers who will use agentic workflows to also fix and update manual documentation at the same time.

The second one - I think it's worth mentioning that isolated setup already handles the case with not sharing credentials with the agent. This might be not obvious, and maybe we would like to add some "additional" gates aroudn it - but referring to the isolated setup and explaining how it plays out here to fulfilll the expectations might be a good idea.

[potiuk]

Also turning to draft - I think it needs more pairs of eyes and reviews - I will ask in the main thread as things that we have now needing more attention than "quick fixes to existing PRs"

[andreahlert]

Both points land. Manual-followable path as a first-class invariant is the right framing — encoding the manual doc as the source of truth (not the steward config) flips the whole adoption story: the agent becomes an assistant to the doc, not a replacement for it.

I'll lift this into spec.md as a cross-cutting commitment alongside the existing "agent never holds the key" / "agent never publishes" pair, plus a skill that diffs the manual doc against what actually happened during the RC and proposes the post-release reconciliation PR (folding into release-audit-report rather than adding an 11th skill).

Replied to the isolation point in the inline thread below.

[justinmclean]

I validated this skill against the recent ASF Policy MCP I created, so most of my comments come from that, but they also match with my knowledge of releases.

[justinmclean]

You may also want to consider adding a step to publish to other distribution areas and validate them; that's an area a lot of projects get wrong, but there's no need for that to be in the first release of this.

[andreahlert]

I validated this skill against the recent ASF Policy MCP I created, so most of my comments come from that, but they also match with my knowledge of releases.

cross-checked the MUST-level items against release-policy.html while applying these. it confirms the @apache.org sender, the 1h wait, dist/release being PMC-write by default, and the expedited explanation + board report. the MD5/SHA-1 prohibition isn't on that page, it's in release-distribution.html, and the doc cites that one for it. so the citations point at the canonical source now.

I am not that expert level 😄 , so it is based on my interpretation level. Please, feel free to advise me more.

[andreahlert]

You may also want to consider adding a step to publish to other distribution areas and validate them; that's an area a lot of projects get wrong, but there's no need for that to be in the first release of this.

good idea, agreed it's out of scope for this first docs PR. added it as a deferred open question in spec.md so it's not lost, and we can open an issue as soon as this PR passes.

[potiuk]

Hi @andreahlert — heads-up first: main was just refreshed with pinned-action SHA bumps for actions/cache, github/codeql-action, zizmorcore/zizmor-action, and astral-sh/setup-uv. Those bumps had been blocked by a schema bug in .github/dependabot.yml (the github-actions ecosystem rejected semver-{major,minor,patch}-days cooldown keys), which is now fixed — see #257. A rebase will pull the new SHAs into your branch as a side effect; that's expected.

Now the actual reason for this ping: small conflict in docs/modes.md after the latest main:

• Your branch updates the Triage row to mention release-management with count 12 + 4 proposed.
• Main now has the Triage row reading experimental (pr-management, issue-management, contributor-nomination) | 13.

The resolution is to keep both: add release-management to your status string after contributor-nomination, and update the count to e.g. 13 + 4 proposed (or whatever the right math is after contributor-nomination landed). Could you rebase or merge main in and reconcile? Happy to push the fix to your branch myself if you'd prefer — let me know.

[andreahlert]

Hi @andreahlert — heads-up first: main was just refreshed with pinned-action SHA bumps for actions/cache, github/codeql-action, zizmorcore/zizmor-action, and astral-sh/setup-uv. Those bumps had been blocked by a schema bug in .github/dependabot.yml (the github-actions ecosystem rejected semver-{major,minor,patch}-days cooldown keys), which is now fixed — see #257. A rebase will pull the new SHAs into your branch as a side effect; that's expected.

Now the actual reason for this ping: small conflict in docs/modes.md after the latest main:

• Your branch updates the Triage row to mention release-management with count 12 + 4 proposed.
• Main now has the Triage row reading experimental (pr-management, issue-management, contributor-nomination) | 13.

The resolution is to keep both: add release-management to your status string after contributor-nomination, and update the count to e.g. 13 + 4 proposed (or whatever the right math is after contributor-nomination landed). Could you rebase or merge main in and reconcile? Happy to push the fix to your branch myself if you'd prefer — let me know.

Think is okay right now. Could you take extra look?

[justinmclean]

See comments once done, consider approved.

[potiuk]

Hi @andreahlert — was sweeping the PR queue and tried a maintainer-side rebase to bring this onto current main, but the conflicts in README.md and docs/modes.md aren't mechanical: the mode taxonomy on main has evolved (mode counts changed, Mentoring and Pairing moved from "proposed" to "experimental"), so wiring the release-management family into the families table needs a real composition pass.

Whenever you next pick this up, a rebase from your end would be great. You'll also pick up the new tests-ok umbrella CI job from #341, which replaces the individual pytest (...) matrix entries in .asf.yaml.

No rush — just flagging so it's not a surprise on next push.

[andreahlert]

Hi @andreahlert — was sweeping the PR queue and tried a maintainer-side rebase to bring this onto current main, but the conflicts in README.md and docs/modes.md aren't mechanical: the mode taxonomy on main has evolved (mode counts changed, Mentoring and Pairing moved from "proposed" to "experimental"), so wiring the release-management family into the families table needs a real composition pass.

Whenever you next pick this up, a rebase from your end would be great. You'll also pick up the new tests-ok umbrella CI job from #341, which replaces the individual pytest (...) matrix entries in .asf.yaml.

No rush — just flagging so it's not a surprise on next push.

rebased. merge in c447a81, only real conflict was the Pairing row in docs/modes.md — kept your experimental | 1 from #251, didn't regress it

also synced the mentoring row in README.md to experimental since #252 already moved it there in modes.md but README was still saying "proposed — not yet formally adopted"

.asf.yaml auto-merged clean, picked up the tests-ok umbrella from #341. CI is running now

while I was in there I also fixed the two diagram nits @justinmclean had left open on process.md (flowchart edges + stateDiagram terminals), commit 9056cbb

[potiuk]

Re-look since my May 15 approval: the substantive iteration with @justinmclean
on Steps 12/13/14 is now landed in the branch — flowchart has S11 → S12,
S11 → S13, S11 → S14 as three independent terminals (no S12→S13 / S14→S13
edges), and the stateDiagram has announced → archived, announced → audited,
announced → bumped all terminating at [*]. Both match what Justin asked
for in his May 25 follow-up.

The 10-skill family spec is well-grounded: the four cross-cutting boundaries
(especially Boundary 1 — agent never holds the RM's signing key) match
the security-cve-allocate pattern of "emit paste-ready commands, human
runs them" and slot cleanly into RFC-AI-0004 Principle 1. The 3-dimension
backend abstraction (release_dist_backend / release_approval_mechanism /
release_announce_backend) makes non-ASF adopters first-class from day one.
Approve from me on the substance.

One thing left before merge: rebase

The branch is 25 commits behind main and the conflicts in README.md
(families table) and docs/modes.md (modes table) aren't mechanical — main
evolved while this PR sat:

• Triage row count moved from "10 shipping + 4 proposed" → 13
• Mentoring moved from proposed (0 skills) → experimental (1 skill)
• Pairing moved from proposed (0 skills) → experimental (1 skill)
• Drafting count moved from "1 shipping + 6 proposed" → 2

These need composing with this PR's release-management additions to each
row — not just an ours / theirs resolution. Same shape as the conflict
I flagged in the earlier bulk-rebase session. Best done by you since the
right composition depends on exactly how you want release-management
framed alongside the post-update other-mode counts.

Once rebased, branch is mergeable.

---

This review was drafted by an AI-assisted tool and confirmed by an Apache Steward
maintainer. The maintainer approving this PR has read the findings and signed off.
If something feels off, please reply on the PR and a maintainer will follow up.

More on how Apache Steward handles maintainer review:
CONTRIBUTING.md.

[andreahlert]

Re-look since my May 15 approval: the substantive iteration with @justinmclean on Steps 12/13/14 is now landed in the branch — flowchart has S11 → S12, S11 → S13, S11 → S14 as three independent terminals (no S12→S13 / S14→S13 edges), and the stateDiagram has announced → archived, announced → audited, announced → bumped all terminating at [*]. Both match what Justin asked for in his May 25 follow-up.

The 10-skill family spec is well-grounded: the four cross-cutting boundaries (especially Boundary 1 — agent never holds the RM's signing key) match the security-cve-allocate pattern of "emit paste-ready commands, human runs them" and slot cleanly into RFC-AI-0004 Principle 1. The 3-dimension backend abstraction (release_dist_backend / release_approval_mechanism / release_announce_backend) makes non-ASF adopters first-class from day one. Approve from me on the substance.

One thing left before merge: rebase

The branch is 25 commits behind main and the conflicts in README.md (families table) and docs/modes.md (modes table) aren't mechanical — main evolved while this PR sat:

• Triage row count moved from "10 shipping + 4 proposed" → 13
• Mentoring moved from proposed (0 skills) → experimental (1 skill)
• Pairing moved from proposed (0 skills) → experimental (1 skill)
• Drafting count moved from "1 shipping + 6 proposed" → 2

These need composing with this PR's release-management additions to each row — not just an ours / theirs resolution. Same shape as the conflict I flagged in the earlier bulk-rebase session. Best done by you since the right composition depends on exactly how you want release-management framed alongside the post-update other-mode counts.

Once rebased, branch is mergeable.

This review was drafted by an AI-assisted tool and confirmed by an Apache Steward
maintainer. The maintainer approving this PR has read the findings and signed off.
If something feels off, please reply on the PR and a maintainer will follow up.
More on how Apache Steward handles maintainer review:
CONTRIBUTING.md.

Done. Could you TAL?