git:20261005.9607433 to git:20261005.9fb9c96

---

# SPDX-License-Identifier: Apache-2.0

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

name: prepare

family: release-management

organization: ASF

mode: Drafting

requires_config:

- release-management-config.md

- release-trains.md

description: |

Draft release preparation artefacts for `<upstream>`: the planning

issue, the version-bump and changelog prep PR (which, on a project's

first release, includes a guided review of what the `git archive`

source artefact ships and the `.gitattributes` `export-ignore`

entries that keep VCS/CI/editor metadata out), or the post-release

development-version bump PR. For ASF projects, the one-time

`automated-signing` setup drafts the Infra key request, the Security

Team notification and the reproducible-build workflow PR. Reads

release metadata from `<project-config>/release-trains.md` and

`<project-config>/release-management-config.md`. Every output is a

draft confirmed by the Release Manager before filing; the agent never

marks a PR ready, never merges, never closes any artefact, never files

a ticket and never sends mail.

when_to_use: |

Invoke when a Release Manager says "prepare the <version> release",

"draft the planning issue for <version>", "open the prep PR for

<version>", "write the version bump for <version>", "draft the

post-release bump for <version>", "review what goes into the source

release", "set up CI release signing", or similar. Covers three

lifecycle moments: planning-issue creation (`/release-prepare

<version>`), version-bump prep PR (`/release-prepare prep <version>`,

which also runs the first-release source-archive review), and

post-release dev-version bump (`/release-prepare post <version>`);

plus the version-less, 🪶 ASF-only `/release-prepare

automated-signing` setup. Requires

`<project-config>/release-management-config.md` and

`<project-config>/release-trains.md` to exist.

argument-hint: "[prep | post] <version> [--review-archive] | automated-signing"

capability: capability:resolve

surface_hash: sha256:43e928f52996ee1b

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)

<default-branch> → upstream repo default branch

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

<product-name> → project display name (e.g. Apache Airflow)

<previous-version> → version tag immediately preceding <version>

<release-branch-base> → base branch for the prep PR (from release_branch_base)

<planning-issue-url> → URL of the created or existing planning issue

<category-x-dependencies> → list of denied dependency identifiers from config

<version-manifest-files> → list of files the version bump touches from config

Substitute these with concrete values from the adopting

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

<project-config>/release-trains.md before running any command below. -->

# release-prepare

<!-- 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 drafts the three preparation artefacts in the

[release-management lifecycle](../../../../docs/release-management/process.md):

Every output is a draft the RM reviews before filing.

This skill composes with:

---

## Golden rules

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

**Golden rule 2 — Category-X is a hard stop.**

**Golden rule 3 — empty change set is a hand-off.**

**Golden rule 4 — NOTICE removals require justification.**

**Golden rule 5 — post-bump scope is constrained.**

**Golden rule 6 — no signing, no `svn` commands.**

---

## Adopter overrides

Before running the default behaviour documented below, this skill

consults

[`.apache-magpie-local/release-prepare.md`](../../../../docs/setup/agentic-overrides.md) (personal, gitignored) and [`.apache-magpie-overrides/release-prepare.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

- **`<project-config>/release-management-config.md` readable** —

For Step 2 (`prep`):

For Step 14 (`post`):

For Step A (`automated-signing`, 🪶 ASF-specific):

---

## Inputs

| Selector | Resolves to |

|---|---|

| `[prep \| post \| automated-signing]` (optional first argument) | Sub-command: `prep` = Step 2, `post` = Step 14, `automated-signing` = Step A (🪶 ASF-only, no `<version>`), omit = Step 1 |

| `<version>` (positional) | Target release version string (a dotted version of two or more numeric parts, no `.postN`, e.g. `2.11.0`) |

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

| `--release-branch <branch>` | Override the base branch for the prep or post PR |

| `--previous-tag <tag>` | Override the previous release tag for the merged-PR query |

| `--skip-empty-check` | Allow Step 1 with an empty merged-PR set; reason logged on planning issue |

---

## Step 0 — Pre-flight check

passing the arguments as the RM typed them:

```bash

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

--skill prepare [prep|post|automated-signing] [<version>] \

[--release-branch <branch>] [--previous-tag <tag>]

```

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

Surface `warnings` and carry on.

Then check what the tool cannot see:

4. **`<upstream>` access.** `gh pr list --repo <upstream>` succeeds.

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

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

Return ONLY valid JSON with this structure:

```json

{

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

"sub_command": "plan" | "prep" | "post" | "automated-signing",

"version": "<version string or null for automated-signing>",

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

"release_branch_base": "<branch>",

"previous_tag": "<tag or null>"

}

```

`verdict` is `"proceed"` only when all hard blockers resolve.

`previous_tag` is `null` when it cannot be determined at pre-flight

---

## Step 1 — Draft the planning issue (sub-command: `plan`)

Read [`plan.md`](plan.md) for this step; it is loaded only for the `plan` sub-command.

---

## Step 2 — Draft the prep PR (sub-command: `prep`)

Read [`prep.md`](prep.md) for this step; it is loaded only for the `prep` sub-command.

---

## Step 14 — Draft the post-release bump PR (sub-command: `post`)

Read [`post.md`](post.md) for this step; it is loaded only for the `post` sub-command.

---

## Step A — Automated release signing setup (sub-command: `automated-signing`, 🪶 ASF-specific)

Read [`automated-signing.md`](automated-signing.md) for this step; it is loaded only for the `automated-signing` sub-command.

---

## Step N+1 — Hand-back artefact

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

**For Step 1 (`plan`):**

**For Step 2 (`prep`):**

- **Category-X check** — confirmed clean (or the violations if blocked).

- **Changelog coverage** — percentage and any uncategorised PRs.

**For Step 14 (`post`):**

- **Post-release bump PR** — URL if opened, or proposed diff and body.

- **Next development version** — restated for clarity.

- **Scope** — confirmed only `version_manifest_files` were modified.

**For Step A (`automated-signing`, 🪶 ASF-specific):**

- **Eligibility** — met, or the conditions still missing.

- **Workflow PR** — URL if opened as a draft, or the rendered file.

---

## Hard rules

- **Never merge any PR.** Merging is the RM's step.

---

## Failure modes

| Symptom | Likely cause | Remediation |

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

| Pre-flight blocked — missing config | `release-management-config.md` absent or missing required key | Add the missing key to the config file |

| Pre-flight blocked — missing train | `release-trains.md` has no entry for `<version>` | Add the release train record |

| Pre-flight blocked (prep) — no planning issue | No `release-planning` issue found for `<version>` | Run Step 1 first, or supply `--planning-issue <url>` |

| Empty PR set | No PRs merged since previous tag | RM decides whether to skip the release; pass `--skip-empty-check` to proceed |

| Category-X hit | A denied dependency appears in the dependency tree | Remove the Category-X dependency before cutting the release |

| NOTICE removal unjustified | Attribution removed for a dependency still in the tree | Justify the removal or revert it |

| Changelog coverage low | Many PRs lack standard labels | RM classifies uncategorised PRs before the prep PR opens |

| Scope violation (prep) | A proposed file is outside the expected set | Confirm the extra file explicitly or remove it from the diff |

| Scope violation (post) | A proposed file is outside `version_manifest_files` | Confirm the extra file explicitly or remove it |

| 2e: proposed exclusion is referenced | A shipped file links to the path (`git grep` hit) | Keep the path, or repoint the reference; never exclude it as-is |

| 2e: symlink chain | A committed symlink points at another symlink | Exclude the relay dir, keep the single-hop canonical link, or replace the relay with a real link |

| 2e: no local clone | `user.md` names no `<upstream>` clone | Set the clone path in `user.md`, or clone and rerun `prep` |

| Step A blocked — not ASF | `project.md` organization is not `ASF` | No action; automated signing is an ASF Infra offering |

| Step A blocked — not demonstrably reproducible | No `release-verify-rc` report with every artefact `identical`, or `reproducibility_*` not set as required | Enable the checks in `release-build.md`, cut and verify an RC, then rerun |

---

## References

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

Steps 1, 2, and 14 context.

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

`release-prepare` per-skill specification.

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

the source-archive review (2e) buckets and rationale, and the 🪶

ASF-specific automated-signing setup (Step A).

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

`§ Source archive` (`source_archive_method`, `export_ignore_reviewed`)

and `§ Reproducibility checks`.

- [`projects/_template/workflows/release-candidate.yml`](../../../magpie-setup/templates/workflows/release-candidate.yml) —

the workflow template Step A renders.

- [`tools/reproducible-archive`](../../../../tools/reproducible-archive/README.md) —

`repro-archive build` / `compare` used for the before/after listing.

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

adopter keys this skill reads (`release_branch_base`,

`version_manifest_files`, `category_x_dependencies`,

`release_planning_issue_template`).

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

release train identity and RM roster.

- `release-keys-sync` (proposed) — downstream Step 3.

- `release-rc-cut` (proposed) — downstream Steps 4–5.

- [ASF release policy](https://www.apache.org/legal/release-policy.html), canonical.

- [ASF licensing-howto](https://www.apache.org/legal/resolved.html) —

Category-A/B/X dependency rules; Category-X is a hard stop for this

skill.