git:20261004.c26005b to git:20261005.9fb9c96

---

# SPDX-License-Identifier: Apache-2.0

# https://www.apache.org/licenses/LICENSE-2.0

name: vote-draft

family: release-management

organization: ASF

mode: Drafting

requires_config:

- release-management-config.md

description: |

Draft the `[VOTE]` email body and planning-issue comment for an

RC of `<upstream>`. Reads RC metadata from the planning issue and

`<project-config>/release-management-config.md`; produces a

ready-to-copy `[VOTE]` subject + body and a proposed planning-issue

comment. Never sends mail and never posts without explicit RM

confirmation.

when_to_use: |

Invoke when a Release Manager says "draft the vote email for

<version>-rcN", "open the vote for <version>-rcN", "write the

[VOTE] thread for <version>", or similar. Appropriate after

`release-verify-rc` reports PASS on the staged RC. Skip if the

release-verify-rc check has not yet been run (or use

`--skip-verify-check` with an explicit reason).

argument-hint: "<version>-rcN [--skip-verify-check <reason>]"

capability: capability:resolve

surface_hash: sha256:6d70a52ead840ca2

license: Apache-2.0

---

<!-- SPDX-License-Identifier: Apache-2.0

https://www.apache.org/licenses/LICENSE-2.0 -->

<!-- Placeholder convention (see ../../AGENTS.md#placeholder-convention-used-in-skill-files):

<project-config> → adopter's project-config directory path

<upstream> → adopter's public source repo (e.g. apache/airflow)

<version> → release version string (e.g. 2.11.0)

<rcN> → release candidate number (e.g. rc1)

<version>-<rcN> → fully-qualified RC identifier (e.g. 2.11.0-rc1)

<staging-url> → URL to the staged RC artefact directory

<tag-url> → URL to the RC tag on the source repository

<keys-url> → URL to the project KEYS file

<changelog-url> → URL to the changelog for this release

<vote-list> → configured vote mailing list (e.g. dev@airflow.apache.org)

Substitute these with concrete values from the adopting

project's <project-config>/release-management-config.md before

running any command below. -->

# release-vote-draft

<!-- BEGIN MAGPIE PREFLIGHT — generated from tools/dev/preflight-block.md -->

## Pre-flight — is this project set up?

Do this **first, before anything else in this skill**, and do it silently.

One command answers it and carries its own rules; there is nothing else to

read.

Run the checker with this skill's own frontmatter `name:` and

`surface_hash:`, and one `--requires` for each `requires_config:` entry:

```bash

PYTHONPATH=.apache-magpie-local python3 -m setup_preflight \

--skill <name> --hash <surface_hash> [--requires <file>]...

```

- **`{"verdict": "ok"}`** → **silent**. Continue into the work the user

asked for and say nothing about pre-flight. This is the ordinary answer.

- **`{"verdict": "action", ...}`** → each finding names a section, and

`rules` carries that section's text. Follow it. The `facts` are the

inputs; what to propose, and what may not be done, are in the rules

rather than here. **Act on a finding only through its rules.**

- **The command did not run at all** — no such module, a non-zero exit, no

`python3` — → never read that as a pass, and do not re-derive the check

by hand: it lives in code so that there is one version of it. If the

project has **no** `.apache-magpie.lock`, `.apache-magpie-local/` or

`.apache-magpie-overrides/`, nothing has been set up here and there is

nothing to reconcile — resolve this skill's `requires_config:` entries

yourself (`.apache-magpie-local/<file>` first, then

`.apache-magpie-overrides/<file>`), stay silent if they all resolve, and

run `/magpie-setup config` for this skill if any does not, which also

installs the checker. Otherwise the project *is* set up and its checker

is missing or stale: say so, propose `/magpie-setup config` to install

it or `/magpie-setup upgrade` to refresh it, and carry on with the work.

**Never run `/magpie-setup adopt` unattended** — not from a finding, not

later in the run, whatever else this skill is doing. It commits a

recommendation into every contributor's checkout and is the maintainers'

decision, taken with the other maintainers.

Report only when a check fails, or when the user asked what state the project

is in. `/magpie-setup verify` is the full diagnostic.

<!-- END MAGPIE PREFLIGHT -->

This skill composes with:

---

## Golden rules

**Golden rule 1 — every state-changing action is a proposal.**

Posting the planning-issue comment requires explicit RM confirmation.

**Golden rule 3 — never shorten the vote window below the floor.**

**Golden rule 4 — expedited votes require an explicit explanation.**

---

## Adopter overrides

Before running the default behaviour documented below, this skill

consults

[`.apache-magpie-local/release-vote-draft.md`](../../../../docs/setup/agentic-overrides.md) (personal, gitignored) and [`.apache-magpie-overrides/release-vote-draft.md`](../../../../docs/setup/agentic-overrides.md) (committed, project-wide)

in the adopter repo if it exists, and applies any agent-readable

overrides it finds.

**Hard rule**: agents NEVER modify the snapshot under

`<adopter-repo>/.apache-magpie/`. Local modifications go in the

override file. Framework changes go via PR to

`apache/magpie`.

---

## Prerequisites

---

## Inputs

| Selector | Resolves to |

|---|---|

| `<version>-rcN` (positional) | RC identifier (a dotted version of two or more numeric parts with no `.postN`, then `-rcN` with N ≥ 1, e.g. `2.11.0-rc1`); must match a staged RC |

| `--skip-verify-check <reason>` | Override the verify-rc gate; reason is logged |

| `--expedited <reason>` | Allow `vote_window_hours` < 72; reason appears in the vote body |

| `--planning-issue <url>` | Explicit planning issue URL (auto-detected if omitted) |

---

## Step 0 — Pre-flight check

Run the deterministic checks with the

[`release-config`](../../../../tools/release-config/README.md) tool,

passing the arguments as the RM typed them:

```bash

uv run --project <framework>/tools/release-config release-config preflight \

--skill vote-draft <version>-rcN [--skip-verify-check <reason>] [--expedited <reason>]

```

Each `blockers` entry is a hard blocker; surface it as written.

Surface `warnings` and carry on.

Copy `skip_verify_override` and `expedited` from `values`.

Then check what the tool cannot see:

3. **Drift check** — the generated pre-flight block reports snapshot drift.

4. **Override consultation** — see *Adopter overrides* above.

Return ONLY valid JSON with this structure:

```json

{

"verdict": "proceed" | "blocked",

"blockers": ["<string describing each hard blocker>"],

"skip_verify_override": true | false,

"expedited": true | false

}

```

---

## Step 1 — Load RC metadata

Load the config-derived fields with the

[`release-config`](../../../../tools/release-config/README.md) tool:

```bash

uv run --project <framework>/tools/release-config release-config load \

--skill vote-draft <version>-rcN

```

Read the rest from the planning issue body and the canned responses:

| Metadata field | Source | Key / location |

|---|---|---|

| `product_name` | `release-management-config.md` | derived from `project_dist_name` (capitalised project display name) |

| `staging_url` | planning issue body | URL under `dist/dev/<project>/<version>-<rcN>/` (for `release_dist_backend = svnpubsub`) |

| `svn_revision` | `svn info <staging_url>` | the committed SVN revision of the staged RC directory (**required** when `release_dist_backend = svnpubsub`; omit for other backends). Read it with `svn info --show-item last-changed-revision <staging_url>` (or `svn log -l1`). SVN branches are mutable, so this pins exactly which artefacts voters reviewed. |

| `tag_url` | planning issue body | URL to the RC git tag |

| `changelog_url` | planning issue body | URL to changelog |

| `atr_revision` | *(optional)* | Specific ATR revision to vote on; omit to use the latest uploaded revision (`atr vote start --revision` defaults to latest — do not hard-depend on a `revisions` lookup) |

| `canned_body` | `<project-config>/canned-responses.md` | `[VOTE]` template block, if present |

| `repro_record` | planning issue body | the reproducibility record `release-rc-cut` posted: source commit, repository URL, the `swh:1:dir:` SWHID of the archive content (with its `origin` / `anchor` qualifiers), `SOURCE_DATE_EPOCH`, sha512 of the source artefact (see [`reproducibility.md`](../../../../docs/release-management/reproducibility.md)); if absent, say so and leave the lines out — never invent them; if only some fields are present, include those |

| `atr_candidate_url` | planning issue body | URL of the candidate's ATR page with its check results (only when `vote_backend = atr`) |

---

## Step 2 — Draft the `[VOTE]` email

Compose the `[VOTE]` subject line and body using the loaded metadata.

```text

[VOTE] Release <Product Name> <version> from <version>-rcN

```

```text

To: <vote_list>

Subject: [VOTE] Release <Product Name> <version> from <version>-rcN

Hi all,

I propose we release the following artifacts as <Product Name> <version>.

The release artifacts, signatures, and checksums are available at:

<staging_url>

(SVN revision: r<svn_revision>) ← include when release_dist_backend = svnpubsub

The release tag to be voted upon:

<tag_url>

The changelog for this release:

<changelog_url>

Keys to verify artifact signatures:

<keys_url>

Convenience artefacts (built from the source above; not the release itself): ← include only when convenience_artefacts is non-empty

<artefact.name> — staged at <staging location> <"— included in this vote" when vote_included>

Each one is verified by rebuilding it from the tag and comparing

(<reproducibility mode>); a convenience artefact that does not

reproduce from the voted source will be withheld from publication.

How to verify this candidate before voting

------------------------------------------

Reproducibility record (from the planning issue): ← include only the lines repro_record provides; omit the block when it has none

repository: <repository URL>

source commit: <commit>

SWHID (content): <swh:1:dir:…;origin=…;anchor=swh:1:rev:…>

SOURCE_DATE_EPOCH: <epoch>

sha512: <sha512 of the source artefact>

Agentic path (any agent with the Magpie release skills, read-only):

/<verification_skill> <version>-rcN

It checks the signature against KEYS, the checksum, licence headers

(RAT), LICENSE/NOTICE, prohibited binaries, dangling links, version

strings, rebuilds the source artefact from the tag to confirm it is

byte-identical to what is staged and that its SWHID is the recorded

one, and rebuilds and compares every convenience artefact.

Manual path (the same checks, longhand):

<verification_doc_url>

Reproducibility background: <reproducibility_doc_url>

ATR check results for this candidate: ← include only when vote_backend = atr

<atr_candidate_url>

[This candidate was signed by CI under the project's automated

release signing. Policy requires a committer's byte-identical rebuild

on their own hardware before promotion: run the verification with

--trusted-hardware --post-to <planning-issue-url> and say so in your

vote.] ← include only when signing_mode = ci-automated

A binding +1 means you downloaded the artefact, verified it, and built

and tested it on your own hardware; the tools above are an aid, not a

substitute (https://www.apache.org/legal/release-policy.html#release-approval).

Please vote to release:

[ ] +1 Release <Product Name> <version>

[ ] +0

[ ] -1 Do not release (please comment with specific reasons)

This vote is open for at least <vote_window_hours> hours.

[EXPEDITED: <reason>. ASF policy requires this deviation to be noted

in the project's next board report.] ← include only when --expedited

[SKIP-VERIFY: release-verify-rc was not run for this RC; the RM

accepted this with the reason: <reason>.] ← include only when --skip-verify-check

Thanks,

<RM name>

```

**Delivery depends on `vote_backend`:**

Emit:

```text

# ATR sends the [VOTE] to <vote_list> and tabulates replies.

# --no-auto-publish is REQUIRED for the hybrid: ATR must NOT publish

# (SVN owns promotion). Confirm current flags with `atr vote start --help`.

atr vote start -m <vote_list> \

--duration <vote_window_hours> \

--subject "<final subject line>" \

--no-auto-publish \

<project> <version>

# Optional: --revision <rev> targets a specific uploaded revision

# (defaults to the latest). Verb/flag names may shift between ATR

# releases — a required `revision` positional was dropped in favour of

# this optional flag, so do not hard-depend on `atr revisions`.

# If `atr check concerns <project> <version>` lists concern-group keys,

# acknowledge them: --concerns-noted <comma,separated,keys>.

```

Return ONLY valid JSON with this structure:

```json

{

"subject": "<final subject line>",

"body": "<final vote email body>",

"vote_window_hours": <integer>,

"vote_backend": "manual" | "atr",

"atr_vote_command": "<atr vote start … or empty when manual>",

"expedited": true | false,

"skip_verify_logged": true | false

}

```

---

## Step 3 — Propose planning-issue comment

```markdown

**Vote open:** `<vote_subject>`

sent to `<vote_list>` on <date> UTC.

Vote window closes: <date+vote_window_hours> UTC (minimum).

Next step: `release-vote-tally` after the window closes.

```

```markdown

**Vote open (expedited):** `<vote_subject>`

sent to `<vote_list>` on <date> UTC.

Vote window closes: <date+vote_window_hours> UTC (minimum, <vote_window_hours>-hour expedited window).

**Expedited:** <reason>.

Reminder: note this deviation in the project's next board report per ASF policy.

Next step: `release-vote-tally` after the window closes.

```

Return ONLY valid JSON with this structure:

```json

{

"comment_body": "<proposed comment text>",

"proposed": true

}

```

---

## Step 4 — Hand-back artefact

The AI-driven part ends with a hand-back artefact containing:

- **RC identifier** — `<version>-<rcN>`.

- **Next step** — `release-vote-tally` after the window closes.

---

## Hard rules

---

## Failure modes

| Symptom | Likely cause | Remediation |

|---|---|---|

| Pre-flight blocked — verify-rc not run | `release-verify-rc` was skipped | Run it, or pass `--skip-verify-check <reason>` |

| Pre-flight blocked — expedited window | `vote_window_hours` < 72 and no `--expedited` | Pass `--expedited <reason>` or raise `vote_window_hours` |

| Metadata field missing | Planning issue lacks staging URL, tag URL, etc. | Provide the missing URL in the planning issue body |

| Subject template renders incorrectly | `vote_subject_template` has unsubstituted placeholders | Check `<project-config>/release-management-config.md` |

| `vote_verification_doc_url` unset | Config predates the *How to verify* section | Add the key (`release-management-config.md § Vote`); until then the body links the framework's `docs/release-management/reproducibility.md` and says the project page is missing |

| Reproducibility record missing from the planning issue | `release-rc-cut` ran before the record was added, or the RM did not paste `repro-archive build`'s output back | Add the commit / `SOURCE_DATE_EPOCH` / sha512 to the planning issue; the body omits the three lines rather than guessing |

---

## References

- [`docs/release-management/process.md`](../../../../docs/release-management/process.md) —

Step 7 context.

- [`docs/release-management/spec.md`](../../../../docs/release-management/spec.md) —

`release-vote-draft` per-skill specification.

- [`<project-config>/release-management-config.md`](../../../magpie-setup/templates/release-management-config.md) —

adopter keys this skill reads (`vote_*`, `vote_verification_doc_url`,

`reproducibility_doc_url`, `vote_verification_skill`).

- [`docs/release-management/reproducibility.md`](../../../../docs/release-management/reproducibility.md) —

what the reproducibility record in the body means and how a voter

uses it.

- [`docs/release-management/manual-release-process.md` § Manual verification](../../../../docs/release-management/manual-release-process.md#manual-verification--what-a-voter-runs-before-1) —

the longhand voter path the framework's own `[VOTE]` links to.

- `release-verify-rc` (proposed) —

upstream step; PASS is a prerequisite, and the agentic path the body

offers voters.

- `release-vote-tally` (proposed) —

downstream step; runs after the vote window closes.

- [ASF release policy § release approval](https://www.apache.org/legal/release-policy.html#release-approval) —

the 72h vote-window floor.