Table of Contents generated with DocToc
KEYS reconciliationdist/dev/[VOTE] thread on dev@[RESULT] [VOTE]dist/dev/ to dist/release/[ANNOUNCE] + site bumpThe authoritative reference for the 14-step release lifecycle and the label-lifecycle state diagram the release-management skills execute against. The family README lists the skills; this document is the process they share. The spec 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 announce@apache.org), 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, not a hard-coded operation. Non-ASF adopters resolve the same abstract step to their own backend; see the Adopter backends section for the dimensions and the per-step backend mapping.
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 announce@apache.org, 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) 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 familyREADME.md, thespec.md, andprojects/_template/release-management-config.mdland first so the lifecycle, the state-change boundaries, and the adopter contract are reviewable independently from the runtime behaviour. The pattern matches Mentoring. Seedocs/modes.md§ Drafting / Triage for status.
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:
security-cve-allocate pattern (Vulnogram URL + paste-ready JSON, human submits) and satisfies RFC-AI-0004 Principle 1.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.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 --> S13 S11 --> S14 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.
Owner: PMC + nominated Release Manager (RM). Skill: release-prepare (proposed), Agentic Drafting.
The RM opens a planning issue listing the target version, the release train it belongs to (see <project-config>/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 and adapts.
Owner: RM. Skill: release-prepare (proposed), Agentic 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). 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.
[!NOTE] The Step 2
LICENSE/NOTICEdraft is provisional. It is drafted before the build, so it covers only content the skill can see in the source tree; build-time-only or generated dependencies are not yet visible. Step 6's Apache RAT pass verifiesLICENSE/NOTICEagainst the actual built artefact, and that verification, not the Step 2 draft, is authoritative.
KEYS reconciliationOwner: RM. Skill: release-keys-sync (proposed), Agentic 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. 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.
Owner: RM. Skill: release-rc-cut (proposed), Agentic Drafting.
The skill emits a paste-ready command sequence:
git tag -s <version>-rcN -m "..." (signed tag, RM's key).<project-config>/release-build.md).gpg --detach-sign --armor <artefact> for each artefact.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
.ascsignatures and.sha512checksums are the ASF baseline; some projects also publish.sha256for older downstream tools.MD5andSHA-1are prohibited for new releases per release-distribution § sigs-and-sums, and signatures are published as detached.asconly, never a binary.sig. The skill reads<project-config>/release-build.mdto determine which digests apply.
dist/dev/Owner: RM. Skill: release-rc-cut (proposed), Agentic Drafting (same skill as Step 4).
The skill emits the svn command sequence to import the artefacts
.asc + .sha512 files into https://dist.apache.org/repos/dist/dev/<project>/<version>-rcN/ (svnpubsub-backed, automatically mirrored to the public dist.apache.org host per the release-distribution documentation). The RM commits with their ASF credentials; the skill never holds those credentials.Output: the staging URL and the candidate artefact list, written back to the planning issue.
Owner: RM (self-check) + any committer who plans to vote. Skill: release-verify-rc (proposed), Agentic Triage / Agentic Pairing.
Read-only. The skill fetches the staged artefacts from dist/dev/<project>/<version>-rcN/, then verifies:
gpg --verify <artefact>.asc <artefact> against the project‘s KEYS file (NOT against the RM’s keyring, Step 3‘s KEYS is the project’s source of truth).sha512sum -c against the published .sha512 (and .sha256 where configured).NOTICE and LICENSE presence at the artefact root, content diff against the previous release.<project-config>/release-build.md binary-exclusion list).The skill emits a pass/fail report to the planning issue. A failure does not auto-flip any label; the RM decides whether to roll a new RC (back to Step 4) or fix the verification source itself (e.g. update RAT excludes).
This skill is the most valuable Agentic Pairing-mode candidate in the family: voters run it in their own dev loop before posting a +1 so the mechanical verification work is done before the human-to-human vote conversation.
[VOTE] thread on dev@Owner: RM. Skill: release-vote-draft (proposed), Agentic Drafting.
The skill drafts the [VOTE] email body to dev@<project> from the planning issue's metadata: version, RC number, staging URL, tag URL, KEYS URL, changelog URL, voting-window deadline (per the release-policy.html § release approval baseline, the configured per-project window in <project-config>/release-management-config.md overrides). The RM sends the email; the skill never sends mail.
The skill simultaneously drafts a [VOTE] notification on the planning issue for committer awareness; that PR / issue comment is also proposed, not auto-posted.
Owner: PMC voters (binding) + committers / community (non-binding). Skill: none, passive window.
No skill runs during the window. The planning issue carries the vote-open label so other skills (Agentic Triage on adjacent issues, Agentic Mentoring on the [VOTE] thread) can spot the window and behave appropriately (e.g. Agentic Mentoring stays out of the [VOTE] thread per its hand-off rules, vote discussion is PMC business).
[RESULT] [VOTE]Owner: RM. Skill: release-vote-tally (proposed), Agentic Triage.
After the window closes, the skill fetches the thread from the project's mail archive (PonyMail by default), parses each reply, classifies each vote (+1 / 0 / -1), determines binding vs non-binding by cross-referencing <project-config>/pmc-roster.md with the From-address, and proposes the [RESULT] [VOTE] body. The RM reviews and sends.
The tally is conservative: when a vote is ambiguous (binding voter posts +1 with one caveat, or +0.5), the skill marks it AMBIGUOUS, needs RM call and refuses to count it. A vote count the RM cannot defend on dev@ is worse than a slow tally.
Pass / fail follows the release-policy.html § release approval baseline (three binding +1 minimum, more binding +1 than -1); the configured per-project rule in <project-config>/release-management-config.md overrides if the project demands stricter conditions.
On fail the planning issue gets the rc-rolled label, the RM returns to Step 4 with a new RC number. The skill never closes the planning issue on a failed vote.
dist/dev/ to dist/release/Owner: RM. Skill: release-promote (proposed), Agentic Drafting.
The skill emits a paste-ready svn mv command set that moves the voted artefacts from https://dist.apache.org/repos/dist/dev/<project>/<version>-rcN/ to https://dist.apache.org/repos/dist/release/<project>/<version>/, together with the commit message template (referencing the [RESULT] [VOTE] archive URL). The RM executes the svn mv + svn commit under their own ASF credentials.
This is the moment of release. The skill writes nothing and runs nothing; the human commit is the act.
The dist/release/ tree is PMC-write-only by default (release-policy.html). If the RM is a committer but not a PMC member, the svn mv will fail; the skill checks PMC membership against the roster and emits an “ask a PMC member to publish” hand-off instead of the command set (see release-promote § hand-off).
[!NOTE] Per release-distribution, mirrors propagate within ~24h. ASF policy also requires waiting at least one hour after the promote
svn commitbefore updating the download page or sending the[ANNOUNCE](release-policy.html). The skill writes the expected mirror-availability time and the earliest-announce time to the planning issue so Step 11 can wait.
[ANNOUNCE] + site bumpOwner: RM ([ANNOUNCE]) + PMC committers (site PR merge). Skill: release-announce-draft (proposed), Agentic Drafting.
Two artefacts:
[ANNOUNCE] email body, addressed to announce@apache.org (mandatory for ASF TLP releases per release-policy.html § announcements) with dev@<project> and users@<project> (or equivalent) on Cc. It may go out no sooner than one hour after the Step 10 promote commit, and the RM must send it from an @apache.org address, the announce list rejects other senders. The body links the project's Download Page, not a direct dist.apache.org URL. The RM sends.closer.lua mirror redirector, never a hard-coded dist.apache.org path (release-distribution). The PR is opened against the site repo configured in <project-config>/site-repo.md; a committer merges.The skill never sends the [ANNOUNCE] email and never merges the site PR.
Owner: RM (or whoever holds release-archive duty per <project-config>/release-management-config.md). Skill: release-archive-sweep (proposed), Agentic Triage.
Per release-distribution § archiving, only the current release line is kept on dist/release/; non-current releases must be moved to archive.apache.org. The skill reads the configured retention rule (per-project, in <project-config>/release-management-config.md; the ASF baseline is “only the latest version of each supported line”), lists releases past retention, and proposes the svn mv sequence to move them to dist/release/<project>/archive/ or the equivalent archive.apache.org location the project's <project-config> declares.
The skill never runs svn mv itself. The RM executes the sequence under their own credentials.
Owner: the framework (per-project audit-log store configured in <project-config>/release-management-config.md). Skill: release-audit-report (proposed), Agentic Triage (read-only dashboard).
Read-only. The skill assembles a per-release record from the planning issue, the [VOTE] and [RESULT] archive URLs, the voter list with binding flags, the RC artefact list with sigs and checksums, the promotion svn revision, and the [ANNOUNCE] archive URL. The output is a structured markdown report appended to the project's audit log (e.g. <project-config>/audit/releases/<version>.md in the adopter repo).
The report is the project's evidence trail for compliance, board reporting, supply-chain queries, and reproducibility. The skill does not modify the artefacts it summarises.
Owner: RM. Skill: release-prepare (proposed), Agentic Drafting (same skill as Steps 1-2, third invocation).
The skill drafts the PR that bumps the development branch to the next -SNAPSHOT / dev / next version, depending on the project's manifest format. Runs in parallel with Step 12, the two steps share no state.
The planning issue carries a single status label at any point. Skills propose label transitions; the RM applies them.
stateDiagram-v2 [*] --> planning planning --> prep_pr_open: Step 1-2 prep_pr_open --> rc_staged: Step 4-5 rc_staged --> vote_open: Step 7 vote_open --> vote_passed: Step 9 (pass) vote_open --> rc_rolled: Step 9 (fail) rc_rolled --> rc_staged: Step 4 (new RC) vote_passed --> promoted: Step 10 promoted --> announced: Step 11 announced --> archived: Step 12 announced --> audited: Step 13 announced --> bumped: Step 14 archived --> [*] audited --> [*] bumped --> [*]
| Label | Applied at | Removed at | Skill that proposes |
|---|---|---|---|
release-planning | Step 1 | Step 2 (prep PR opens) | release-prepare |
prep-pr-open | Step 2 | Step 4 (RC tag exists) | release-prepare |
rc-staged | Step 5 | Step 7 ([VOTE] posted) or Step 9-fail | release-rc-cut |
vote-open | Step 7 | Step 9 | release-vote-draft |
vote-passed | Step 9 (pass) | Step 10 (promote committed) | release-vote-tally |
rc-rolled | Step 9 (fail) | Step 5 (new RC staged) | release-vote-tally |
promoted | Step 10 | Step 11 ([ANNOUNCE] sent) | release-promote |
announced | Step 11 | Step 12 (archive sweep done) | release-announce-draft |
archived | Step 12 | terminal | release-archive-sweep |
The release-audit-report skill (Step 13) reads every label transition but proposes none of its own; it is a dashboard, not a state machine participant.
README.md, family overview, skill table.spec.md, per-skill scope, state-change boundary, hand-off protocol, adopter knobs.projects/_template/release-management-config.md, adopter contract scaffold.docs/modes.md § Drafting, § Triage, the modes the skills inhabit.MISSION.md § Initial Goals, the Cut a first Apache release through the standard process within 3 months commitment this family operationalises.docs/rfcs/RFC-AI-0004.md § Principle 1, the human-in-the-loop rule every state-change boundary in this lifecycle inherits.dist/dev/ + dist/release/ mechanics, mirror propagation, archive policy.KEYS file and signing-key onboarding.