From 7d29144a36950f70ac2bfaa5bbe028d0211d9d51 Mon Sep 17 00:00:00 2001 From: Kavya Katal Date: Tue, 20 Oct 2026 11:11:06 +0530 Subject: [PATCH 1/2] feat(setup): add release-management family first-run welcome guide --- docs/release-management/README.md | 6 ++ .../guides/release-management.md | 58 +++++++++++++++++++ tools/setup-preflight/tests/test_welcome.py | 48 ++++++++++++++- tools/skill-evals/README.md | 2 +- tools/skill-evals/evals/setup/README.md | 4 +- .../case-meta.json | 1 + .../expected.json | 1 + .../report.md | 37 ++++++++++++ .../state.json | 24 ++++++++ .../case-9-first-magpie-run/report.md | 2 +- 10 files changed, 177 insertions(+), 6 deletions(-) create mode 100644 plugins/magpie-setup/skills/setup/setup_preflight/guides/release-management.md create mode 100644 tools/skill-evals/evals/setup/preflight-floor/fixtures/case-16-release-management-first-run/case-meta.json create mode 100644 tools/skill-evals/evals/setup/preflight-floor/fixtures/case-16-release-management-first-run/expected.json create mode 100644 tools/skill-evals/evals/setup/preflight-floor/fixtures/case-16-release-management-first-run/report.md create mode 100644 tools/skill-evals/evals/setup/preflight-floor/fixtures/case-16-release-management-first-run/state.json diff --git a/docs/release-management/README.md b/docs/release-management/README.md index a08938b68..b6fac488d 100644 --- a/docs/release-management/README.md +++ b/docs/release-management/README.md @@ -94,6 +94,12 @@ New to Magpie? The [quick start](../quick-start.md) walks the whole path in one place โ€” install, the first `/magpie-setup:setup` run, and a recording of it happening โ€” plus the other agents and the secure-isolation setup to run next. +The first release-management skill you run opens with a one-minute +[welcome guide](../../plugins/magpie-setup/skills/setup/setup_preflight/guides/release-management.md): +the typical flow, what needs configuring, what to ask it, and how to make it yours. +Dismiss it, or hide it for good, from its last line; +*"show the release-management welcome again"* or `/magpie-setup:welcome-guide release-management` brings it back. + ### Before the first run diff --git a/plugins/magpie-setup/skills/setup/setup_preflight/guides/release-management.md b/plugins/magpie-setup/skills/setup/setup_preflight/guides/release-management.md new file mode 100644 index 000000000..c563d530b --- /dev/null +++ b/plugins/magpie-setup/skills/setup/setup_preflight/guides/release-management.md @@ -0,0 +1,58 @@ + + +# ๐Ÿฆ Magpie here โ€” your release-management sidekick + +A one-minute tour, then straight back to what you asked for. + +## ๐Ÿ”„ The typical flow + +1. ๐Ÿ“‹ **Prepare** the release plan and version bump โ€” *"plan our next release"* +2. ๐Ÿ”‘ **Check KEYS** before RC signing โ€” *"sync the release signing key"* +3. ๐Ÿ“ฆ **Cut an RC** and prepare signing/staging commands โ€” *"cut rc1 for this version"* +4. โœ… **Verify the RC** before a vote โ€” *"verify the staged release candidate"* +5. ๐Ÿ—ณ๏ธ **Draft the vote**, then tally results โ€” *"draft the vote email"* / *"tally the votes"* +6. ๐Ÿš€ **Promote** a release only after approval โ€” *"prepare promotion commands"* +7. ๐Ÿ“ฃ **Draft the announcement**, then review archive cleanup โ€” *"draft the announcement"* +8. ๐Ÿ“Š **Audit** the completed release evidence โ€” *"prepare the release audit report"* + +These steps are guided workflows, not autonomous publishing. +The Release Manager keeps the signing key and runs signing and publication commands. +Vote and announcement emails are drafts, never automatically sent. +Review and explicitly approve proposed external or repository changes. + +## โš™๏ธ Configure it + +Release skills use project-specific configuration: + +- โš™๏ธ **Release policy** โ€” `release-management-config.md` for planning, votes, announcements, archives, audit reports and KEYS +- ๐Ÿ“ฆ **Build and staging** โ€” `release-build.md` for `rc-cut` and `verify-rc` +- ๐Ÿ—ณ๏ธ **Approval roster** โ€” `pmc-roster.md` for `vote-tally` and `promote` + +Choose the appropriate distribution, approval and announcement backends. +Configure personally with `/magpie-setup:setup config`. +Team adoption with `/magpie-setup:setup adopt` is a maintainer decision. + +## ๐Ÿ’ฌ Just ask + +Talk to Magpie in plain language: + +- *"prepare the release plan for our next version"* +- *"check that my public signing key is in KEYS"* +- *"give me the commands to cut and verify rc1"* +- *"draft a vote email for this verified RC"* +- *"tally the release vote and prepare the result draft"* +- *"prepare promotion and announcement after the vote passes"* +- *"review old release archives and generate an audit report"* + +## ๐ŸŽจ Make it yours + +Describe your release policy and preferred backend: + +- *"use our project's configured release distribution backend"* +- *"use the approval mechanism and vote window in our release policy"* + +Review proposed configuration or override changes before applying them. +Useful elsewhere? Ask *"upstream this change to Magpie"* to prepare a contribution for review. + + diff --git a/tools/setup-preflight/tests/test_welcome.py b/tools/setup-preflight/tests/test_welcome.py index 715299468..37da502fc 100644 --- a/tools/setup-preflight/tests/test_welcome.py +++ b/tools/setup-preflight/tests/test_welcome.py @@ -34,7 +34,17 @@ REPO_ROOT = Path(__file__).resolve().parents[3] SECURITY_SKILL = "issue-sync" -OTHER_SKILL = "rc-cut" +# Every shipped family now has a guide, so the "family without a guide" +# cases use a synthetic one registered for the duration of each test. +OTHER_SKILL = "example-guideless-skill" +OTHER_FAMILY = "example-guideless-family" + + +@pytest.fixture +def guideless_family(monkeypatch: pytest.MonkeyPatch) -> None: + from setup_preflight import families + + monkeypatch.setitem(families.SKILL_FAMILIES, OTHER_SKILL, OTHER_FAMILY) def stamp(root: Path) -> dict: @@ -207,6 +217,28 @@ def test_the_setup_family_guide_comes_on_the_next_run(project: Path, version) -> assert due(project, "status") == [("general", "again")] +def test_the_release_management_family_guide_comes_on_the_next_run(project: Path, version) -> None: + for skill in ( + "announce-draft", + "archive-sweep", + "audit-report", + "keys-sync", + "prepare", + "promote", + "rc-cut", + "verify-rc", + "vote-draft", + "vote-tally", + ): + assert welcome.family_of(skill) == "release-management" + + assert due(project, "rc-cut") == [("general", "first-run")] + welcome.record(project, "general", "seen") + assert due(project, "rc-cut") == [("release-management", "first-run")] + welcome.record(project, "release-management", "seen") + assert due(project, "rc-cut") == [("general", "again")] + + def test_at_most_one_guide_per_run(project: Path, version) -> None: for _ in range(8): found = welcome_findings(project, SECURITY_SKILL) @@ -229,8 +261,10 @@ def test_a_hidden_general_guide_does_not_hold_back_the_family_one(project: Path, assert due(project) == [("security", "first-run")] +@pytest.mark.usefixtures("guideless_family") def test_a_skill_of_a_family_without_a_guide_gets_only_the_general_one(project: Path, version) -> None: - assert welcome.family_of(OTHER_SKILL) == "release-management" + assert welcome.family_of(OTHER_SKILL) == OTHER_FAMILY + assert OTHER_FAMILY not in welcome.family_guides() assert due(project, OTHER_SKILL) == [("general", "first-run")] welcome.record(project, "general", "never") assert due(project, OTHER_SKILL) == [] @@ -293,6 +327,7 @@ def test_no_welcome_leaves_it_out(project: Path, capsys, version) -> None: # --- the three answers ---------------------------------------------------------------- +@pytest.mark.usefixtures("guideless_family") def test_seen_shows_again_and_stops_after_three(project: Path, version) -> None: reasons = [] for _ in range(5): @@ -311,6 +346,7 @@ def test_a_later_answer_replaces_seen_without_counting_twice(project: Path, vers assert entry["shown"] == 1 +@pytest.mark.usefixtures("guideless_family") def test_dismiss_hides_it_until_the_version_changes(project: Path, version) -> None: welcome.record(project, "general", "dismiss") assert codes(project, OTHER_SKILL) == [] @@ -319,12 +355,14 @@ def test_dismiss_hides_it_until_the_version_changes(project: Path, version) -> N assert [f.facts["reason"] for f in found] == ["upgraded"] +@pytest.mark.usefixtures("guideless_family") def test_never_persists_across_versions(project: Path, version) -> None: welcome.record(project, "general", "never") version[0] = "1.0.0" assert codes(project, OTHER_SKILL) == [] +@pytest.mark.usefixtures("guideless_family") def test_enable_clears_the_choice(project: Path, version) -> None: welcome.record(project, "general", "never") assert welcome.enable(project, "general") is True @@ -515,6 +553,7 @@ def test_the_rules_section_and_all_guides_ship() -> None: "contributor-growth", "repo-health", "setup", + "release-management", } <= set(welcome.guides()) assert welcome.family_guides() == [g for g in welcome.guides() if g != "general"] @@ -532,6 +571,7 @@ def test_the_rules_section_and_all_guides_ship() -> None: "contributor-growth", "repo-health", "setup", + "release-management", ], ) def test_each_guide_is_short_and_ends_with_the_way_back(name: str) -> None: @@ -562,6 +602,7 @@ def test_the_footer_is_shared_and_filled_in_per_guide() -> None: contributor_growth = welcome.guide("contributor-growth") or "" repo_health = welcome.guide("repo-health") or "" setup = welcome.guide("setup") or "" + release_management = welcome.guide("release-management") or "" for text in ( security, general, @@ -573,6 +614,7 @@ def test_the_footer_is_shared_and_filled_in_per_guide() -> None: contributor_growth, repo_health, setup, + release_management, ): assert "{{" not in text assert "welcome footer: generated" not in text @@ -596,6 +638,8 @@ def test_the_footer_is_shared_and_filled_in_per_guide() -> None: assert "--family repo-health --color=always" in repo_health assert "`/magpie-setup:welcome-guide setup`" in setup assert "--family setup --color=always" in setup + assert "`/magpie-setup:welcome-guide release-management`" in release_management + assert "--family release-management --color=always" in release_management def test_list_prints_every_guide(capsys) -> None: diff --git a/tools/skill-evals/README.md b/tools/skill-evals/README.md index 0671324f7..fabbfb775 100644 --- a/tools/skill-evals/README.md +++ b/tools/skill-evals/README.md @@ -11,7 +11,7 @@ Behavioral eval harness for Apache Magpie skills. Each eval suite tests a skill Suites are currently implemented for: -- **setup** โ€” 140 cases across 30 steps (step-verify-drift, step-overrides-surface, step-override-bypass, step-m3-baseline-pick, step-m4-install-gates, step-m5-no-repo-offer, step-m5-companion-offer, step-upgrade-companion-offer, step-adopt-settings-merge, verify-default-set, uninstall-default-set, lock-marketplace-parse, adopt-write-floor, setup-prefill-from-floor, preflight-floor, upgrade-adoption-split, verify-floor, adopt-review-process, adopt-security-list, step-reconcile, step-verify, step-config-stamp, step-config-adversarial, step-config-mail, step-adopt-stamp, step-upgrade-stamp, step-delegate-propose, config-vcs-backend, config-local-custom-parser) +- **setup** โ€” 141 cases across 30 steps (step-verify-drift, step-overrides-surface, step-override-bypass, step-m3-baseline-pick, step-m4-install-gates, step-m5-no-repo-offer, step-m5-companion-offer, step-upgrade-companion-offer, step-adopt-settings-merge, verify-default-set, uninstall-default-set, lock-marketplace-parse, adopt-write-floor, setup-prefill-from-floor, preflight-floor, upgrade-adoption-split, verify-floor, adopt-review-process, adopt-security-list, step-reconcile, step-verify, step-config-stamp, step-config-adversarial, step-config-mail, step-adopt-stamp, step-upgrade-stamp, step-delegate-propose, config-vcs-backend, config-local-custom-parser) - **setup-isolated-setup-install** โ€” 19 cases across 5 steps (runtime-routing, step-snapshot-drift, step-scope-confirm, step-hardware-key, step-roborev-exclusion) - **setup-privacy-llm** โ€” 6 cases across 2 steps (step-1-resolve, step-4-gate) - **setup-shared-config-sync** โ€” 12 cases across 2 steps (step-3-decide-action, step-5-draft-commit) diff --git a/tools/skill-evals/evals/setup/README.md b/tools/skill-evals/evals/setup/README.md index c6d1d863c..fe5336d5e 100644 --- a/tools/skill-evals/evals/setup/README.md +++ b/tools/skill-evals/evals/setup/README.md @@ -5,7 +5,7 @@ Behavioral evals for the `setup` skill. -## Suites (140 cases total) +## Suites (141 cases total) | Suite | Step | Cases | What it covers | |---|---|---|---| @@ -25,7 +25,7 @@ Behavioral evals for the `setup` skill. | adopt-review-process | adopt.md ยง Step 4c | 5 | a fresh adopt finding two deviations in the confirmed documents where one is accepted and one rejected, and a release policy left alone because that family is not in the floor; a re-adoption reviewing only the one family the floor diff added; a re-adoption that adds no family, where edited process documents are still not re-read; a sentence that would weaken a merge confirmation gate, dropped and named while a label deviation beside it is written; and a repo whose only candidate document the maintainer un-ticks, skipping the step | | adopt-security-list | adopt.md ยง Step 4b | 4 | an ASF project whose dedicated security list is in its docs and on the ASF page (recommend `security@`); an ASF project with no dedicated list (no recommendation, `private@` only as a flagged fallback); a non-ASF project, which is not asked; and conflicting evidence between `SECURITY.md` and the ASF page (no recommendation, flagged fallback) | | setup-prefill-from-floor | install.md ยง Step M0b | 4 | adopted (propose the floor), unadopted (framework defaults), a foreign marketplace called out, and a snapshot lock falling through | -| preflight-floor | preflight-block.md ยง Pre-flight | 20 | at floor (silent), below floor (update), plugin missing (install), foreign marketplace (ask first, run nothing), no `claude` CLI (print), unadopted (propose setup), `apache/magpie` in an alarming context (update anyway, unasked), unreadable `claude plugin list --json` (silent, treated as unknown not absent), first Magpie run (show the general welcome guide, record it, carry on), first utilities run (show the utilities welcome guide, record it, carry on), first mentoring run (show the mentoring welcome guide, record it, carry on), first pairing run (show the pairing welcome guide, record it, carry on), first issue run (show the issue welcome guide, record it, carry on), first pr-management run (show the pr-management welcome guide, record it, carry on), first contributor-growth run (show the contributor-growth welcome guide, record it, carry on), below floor on Codex (marketplace upgrade), below floor on Gemini (update the extension once), at floor on Gemini (silent), first repo-health run (show the repo-health welcome guide, record it, carry on), first setup run (show the setup welcome guide, record it, carry on) | +| preflight-floor | preflight-block.md ยง Pre-flight | 21 | at floor (silent), below floor (update), plugin missing (install), foreign marketplace (ask first, run nothing), no `claude` CLI (print), unadopted (propose setup), `apache/magpie` in an alarming context (update anyway, unasked), unreadable `claude plugin list --json` (silent, treated as unknown not absent), first Magpie run (show the general welcome guide, record it, carry on), first utilities run (show the utilities welcome guide, record it, carry on), first mentoring run (show the mentoring welcome guide, record it, carry on), first pairing run (show the pairing welcome guide, record it, carry on), first issue run (show the issue welcome guide, record it, carry on), first pr-management run (show the pr-management welcome guide, record it, carry on), first contributor-growth run (show the contributor-growth welcome guide, record it, carry on), below floor on Codex (marketplace upgrade), below floor on Gemini (update the extension once), at floor on Gemini (silent), first repo-health run (show the repo-health welcome guide, record it, carry on), first setup run (show the setup welcome guide, record it, carry on), first release-management run (show the release-management welcome guide, record it, carry on) | | upgrade-adoption-split | upgrade.md ยง Step 0b | 4 | not adopted (nothing staged), adopted (floor raised and staged), already ahead (floor unchanged), snapshot method (falls through) | | verify-floor | verify.md ยง Adoption floor | 4 | no lock (not a fault), ahead of floor with extra plugins (not a fault), a shortfall (a fault), a floor plugin the marketplace no longer ships (a fault, not installed around) | | step-reconcile | reconcile.md ยง The sweep | 3 | a clean sweep on a pinned-snapshot install (anchor present, config resolved โ€” stamp written, nothing proposed), a renamed step heading stranding an override's anchor (one re-anchor proposal named), a marketplace install whose plugin cache is sandbox-denied (anchor resolution left `unchecked`, config resolution still completes) | diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-16-release-management-first-run/case-meta.json b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-16-release-management-first-run/case-meta.json new file mode 100644 index 000000000..88c1f39aa --- /dev/null +++ b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-16-release-management-first-run/case-meta.json @@ -0,0 +1 @@ +{"tags":["local-smoke"]} diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-16-release-management-first-run/expected.json b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-16-release-management-first-run/expected.json new file mode 100644 index 000000000..2adc36dfb --- /dev/null +++ b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-16-release-management-first-run/expected.json @@ -0,0 +1 @@ +{"action": "welcome", "commands": [], "blocks": false} diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-16-release-management-first-run/report.md b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-16-release-management-first-run/report.md new file mode 100644 index 000000000..a313497a8 --- /dev/null +++ b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-16-release-management-first-run/report.md @@ -0,0 +1,37 @@ + + +There is no `.apache-magpie.lock`, no `.apache-magpie-overrides/` and no +`.apache-magpie-local/` at the repo root. The running agent is Claude Code +with magpie-setup 0.4.0 and magpie-release-management 0.4.0 installed. + +The user has already seen the initial general welcome guide on an earlier run. +The invoked skill's own frontmatter reads `name: rc-cut` and +`surface_hash: sha256:60623e456e72bbf6`; it belongs to the +release-management family. This is the first time a release-management +skill has run here. The user asked it to "cut rc1 for the next release". + +The pre-flight command printed: + +```json +{ + "findings": [ + { + "code": "welcome", + "facts": { + "family": "release-management", + "guide": "# \ud83d\udc26 Magpie here \u2014 your release-management sidekick\n\nA one-minute tour, then straight back to what you asked for.\n\n## \ud83d\udd04 The typical flow\n\n1. \ud83d\udccb **Prepare** the release plan and version bump \u2014 *\"plan our next release\"*\n2. \ud83d\udd11 **Check KEYS** before RC signing \u2014 *\"sync the release signing key\"*\n3. \ud83d\udce6 **Cut an RC** and prepare signing/staging commands \u2014 *\"cut rc1 for this version\"*\n4. \u2705 **Verify the RC** before a vote \u2014 *\"verify the staged release candidate\"*\n5. \ud83d\uddf3\ufe0f **Draft the vote**, then tally results \u2014 *\"draft the vote email\"* / *\"tally the votes\"*\n6. \ud83d\ude80 **Promote** a release only after approval \u2014 *\"prepare promotion commands\"*\n7. \ud83d\udce3 **Draft the announcement**, then review archive cleanup \u2014 *\"draft the announcement\"*\n8. \ud83d\udcca **Audit** the completed release evidence \u2014 *\"prepare the release audit report\"*\n\nThese steps are guided workflows, not autonomous publishing.\nThe Release Manager keeps the signing key and runs signing and publication commands.\nVote and announcement emails are drafts, never automatically sent.\nReview and explicitly approve proposed external or repository changes.\n\n## \u2699\ufe0f Configure it\n\nRelease skills use project-specific configuration:\n\n- \u2699\ufe0f **Release policy** \u2014 `release-management-config.md` for planning, votes, announcements, archives, audit reports and KEYS\n- \ud83d\udce6 **Build and staging** \u2014 `release-build.md` for `rc-cut` and `verify-rc`\n- \ud83d\uddf3\ufe0f **Approval roster** \u2014 `pmc-roster.md` for `vote-tally` and `promote`\n\nChoose the appropriate distribution, approval and announcement backends.\nConfigure personally with `/magpie-setup:setup config`.\nTeam adoption with `/magpie-setup:setup adopt` is a maintainer decision.\n\n## \ud83d\udcac Just ask\n\nTalk to Magpie in plain language:\n\n- *\"prepare the release plan for our next version\"*\n- *\"check that my public signing key is in KEYS\"*\n- *\"give me the commands to cut and verify rc1\"*\n- *\"draft a vote email for this verified RC\"*\n- *\"tally the release vote and prepare the result draft\"*\n- *\"prepare promotion and announcement after the vote passes\"*\n- *\"review old release archives and generate an audit report\"*\n\n## \ud83c\udfa8 Make it yours\n\nDescribe your release policy and preferred backend:\n\n- *\"use our project's configured release distribution backend\"*\n- *\"use the approval mechanism and vote window in our release policy\"*\n\nReview proposed configuration or override changes before applying them.\nUseful elsewhere? Ask *\"upstream this change to Magpie\"* to prepare a contribution for review.\n\n## \ud83d\udc4b About this guide\n\n- **Continue** \u2014 show it again next time (three times at most)\n- **Dismiss** \u2014 hide it until the next Magpie upgrade\n- **Don't show again** \u2014 hide it for good; say *\"show the release-management welcome again\"* to bring it back\n\nShow this again any time: `/magpie-setup:welcome-guide release-management`\n(`/magpie-setup-welcome-guide release-management` on a pinned snapshot).\n\n\ud83c\udf08 Prefer it in colour? Run this yourself \u2014 the `!` prefix runs it as a shell command:\n\n```text\n! PYTHONPATH=\".apache-magpie-local:$(git rev-parse --git-common-dir)/../.apache-magpie-local:$(git rev-parse --git-common-dir)/apache-magpie\" python3 -m setup_preflight.welcome show --family release-management --color=always\n```\n", + "max_shown": 3, + "reason": "first-run", + "shown": 0 + }, + "scope": "family", + "section": "welcome" + } + ], + "rules": { + "welcome": "## welcome \u2014 a first-run welcome guide is due\n\nA welcome guide is due on this run: `facts.family` names it\n(`general`, for the first Magpie skill this user runs here, or the skill's own family),\nand `facts.reason` says why (`first-run`, `again`, or `upgraded` after a dismissal).\n`facts.guide` is the guide. The checker shows at most one guide per run and has already picked it.\n\n1. **Show `facts.guide` to the user verbatim**, as Markdown, before the work they asked for.\n Do not summarise, reword, trim, or add to it, and substitute nothing in it:\n its placeholders (``, ``, ``, \u2026) are meant to be read as written.\n2. **Offer the three choices in one line**:\n **Continue** (show again next time) \u00b7 **Dismiss** (hide until the next Magpie upgrade) \u00b7 **Don't show again**.\n3. **Record `seen` at once**, which is what no answer means, then carry on with the user's request in the same turn.\n Never block the requested work on the guide, and never wait for an answer before starting it.\n4. **When the user picks Dismiss or Don't show again** \u2014 now or later in the session \u2014 record that choice;\n it replaces `seen`. Continue needs nothing further.\n\n```bash\nPYTHONPATH=\".apache-magpie-local:$(git rev-parse --git-common-dir)/../.apache-magpie-local:$(git rev-parse --git-common-dir)/apache-magpie\" \\\n python3 -m setup_preflight.welcome record --family --choice \n```\n\n`seen` brings the guide back on a later run, `facts.max_shown` recorded showings in all (`facts.shown` so far);\n`dismiss` hides it until the framework version changes; `never` hides it until re-enabled.\nEvery write merges into the personal layer's `reconciled.json` under `welcome.`, keeping every other key;\nnever write it by hand.\nIf the command exits non-zero, say nothing more about it and carry on.\n\nAny guide can be shown again on request with `/magpie-setup:welcome-guide []`,\nwhich also turns a hidden one back on." + }, + "verdict": "action" +} +``` diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-16-release-management-first-run/state.json b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-16-release-management-first-run/state.json new file mode 100644 index 000000000..adacd74bf --- /dev/null +++ b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-16-release-management-first-run/state.json @@ -0,0 +1,24 @@ +{ + "lock": null, + "plugins": [ + [ + "magpie-setup", + "0.4.0" + ], + [ + "magpie-release-management", + "0.4.0" + ] + ], + "reconciled": { + "welcome": { + "general": { + "choice": "seen", + "shown": 1 + } + } + }, + "skill": "rc-cut", + "welcome": true, + "hash": "sha256:60623e456e72bbf6" +} diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-9-first-magpie-run/report.md b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-9-first-magpie-run/report.md index 504dac927..ce1b5e8c9 100644 --- a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-9-first-magpie-run/report.md +++ b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-9-first-magpie-run/report.md @@ -20,7 +20,7 @@ The pre-flight command printed: "code": "welcome", "facts": { "family": "general", - "guide": "# \ud83d\udc26 Hello from Magpie \u2014 your project's maintainer sidekick\n\nOne minute, then straight back to what you asked for.\n\n## \ud83d\ude80 Getting started\n\n- \ud83d\udce6 **Install** from your agent's marketplace (Claude Code shown):\n `/plugin marketplace add apache/magpie`,\n then `/plugin install magpie-setup@apache-magpie` and one `/plugin install magpie-@apache-magpie` per family you want\n- \ud83d\ude4b **Configure it for yourself** \u2014 personal settings, nothing committed \u2014 `/magpie-setup:setup config`\n- \ud83d\udc65 **Adopt it for your project** \u2014 the configuration is committed to your repo and shared with every contributor \u2014\n `/magpie-setup:setup adopt` (a maintainers' decision)\n\nOn a pinned-snapshot install the commands are shorter: `/magpie-setup config`, `/magpie-setup adopt`.\n\n## \ud83d\udd04 Staying current\n\n- \u270b **By hand:** `claude plugin marketplace update apache-magpie`, then `claude plugin update @apache-magpie`\n- \ud83e\udd16 **Automatically (Claude Code):** `/plugin` \u2192 **Marketplaces** \u2192 **apache-magpie** \u2192 **Enable auto-update** \u2014\n it is off by default for third-party marketplaces like this one\n- \ud83e\udde9 Gemini CLI takes `--auto-update` at install time; Codex has no auto-update, so run `codex plugin marketplace upgrade apache-magpie`\n\nAfter an update, the next skill you run checks your configuration against it and proposes any fixes;\n`/magpie-setup:setup reconcile` checks everything at once (on a pinned snapshot, `/magpie-setup upgrade` does the update).\n\n## \ud83d\udcac Just ask\n\nTalk to Magpie in plain language \u2014 no syntax to learn.\nNothing is written, posted, or sent without your OK.\nInterrupt at any time, say no, or change your mind halfway through.\n\n## \ud83c\udfa8 You are the creator\n\nDescribe what you want a skill to do for you:\n\n- *\"from now on, always ask me before closing a stale issue\"*\n- *\"when you triage PRs, leave the bot-authored ones alone\"*\n\nMagpie records it as an override for that skill (`/magpie-setup:setup override `).\nWorth sharing? Say *\"upstream this change to Magpie\"* \u2014 it makes the change generic and opens a PR to `apache/magpie` for you to review (`/magpie-setup:override-upstream`).\n\n## \ud83d\udcda More guides\n\nEach family can bring its own short guide, shown the first time you use it:\n\n- `contributor-growth` \u2014 `/magpie-setup:welcome-guide contributor-growth`\n- `issue` \u2014 `/magpie-setup:welcome-guide issue`\n- `mentoring` \u2014 `/magpie-setup:welcome-guide mentoring`\n- `pairing` \u2014 `/magpie-setup:welcome-guide pairing`\n- `pr-management` \u2014 `/magpie-setup:welcome-guide pr-management`\n- `repo-health` \u2014 `/magpie-setup:welcome-guide repo-health`\n- `security` \u2014 `/magpie-setup:welcome-guide security`\n- `setup` \u2014 `/magpie-setup:welcome-guide setup`\n- `utilities` \u2014 `/magpie-setup:welcome-guide utilities`\n\n## \ud83d\udc4b About this guide\n\n- **Continue** \u2014 show it again next time (three times at most)\n- **Dismiss** \u2014 hide it until the next Magpie upgrade\n- **Don't show again** \u2014 hide it for good; say *\"show the Magpie welcome again\"* to bring it back\n\nShow this again any time: `/magpie-setup:welcome-guide []`\n(`/magpie-setup-welcome-guide []` on a pinned snapshot).\n\n\ud83c\udf08 Prefer it in colour? Run this yourself \u2014 the `!` prefix runs it as a shell command:\n\n```text\n! PYTHONPATH=\".apache-magpie-local:$(git rev-parse --git-common-dir)/../.apache-magpie-local:$(git rev-parse --git-common-dir)/apache-magpie\" python3 -m setup_preflight.welcome show --family general --color=always\n```\n", + "guide": "# \ud83d\udc26 Hello from Magpie \u2014 your project's maintainer sidekick\n\nOne minute, then straight back to what you asked for.\n\n## \ud83d\ude80 Getting started\n\n- \ud83d\udce6 **Install** from your agent's marketplace (Claude Code shown):\n `/plugin marketplace add apache/magpie`,\n then `/plugin install magpie-setup@apache-magpie` and one `/plugin install magpie-@apache-magpie` per family you want\n- \ud83d\ude4b **Configure it for yourself** \u2014 personal settings, nothing committed \u2014 `/magpie-setup:setup config`\n- \ud83d\udc65 **Adopt it for your project** \u2014 the configuration is committed to your repo and shared with every contributor \u2014\n `/magpie-setup:setup adopt` (a maintainers' decision)\n\nOn a pinned-snapshot install the commands are shorter: `/magpie-setup config`, `/magpie-setup adopt`.\n\n## \ud83d\udd04 Staying current\n\n- \u270b **By hand:** `claude plugin marketplace update apache-magpie`, then `claude plugin update @apache-magpie`\n- \ud83e\udd16 **Automatically (Claude Code):** `/plugin` \u2192 **Marketplaces** \u2192 **apache-magpie** \u2192 **Enable auto-update** \u2014\n it is off by default for third-party marketplaces like this one\n- \ud83e\udde9 Gemini CLI takes `--auto-update` at install time; Codex has no auto-update, so run `codex plugin marketplace upgrade apache-magpie`\n\nAfter an update, the next skill you run checks your configuration against it and proposes any fixes;\n`/magpie-setup:setup reconcile` checks everything at once (on a pinned snapshot, `/magpie-setup upgrade` does the update).\n\n## \ud83d\udcac Just ask\n\nTalk to Magpie in plain language \u2014 no syntax to learn.\nNothing is written, posted, or sent without your OK.\nInterrupt at any time, say no, or change your mind halfway through.\n\n## \ud83c\udfa8 You are the creator\n\nDescribe what you want a skill to do for you:\n\n- *\"from now on, always ask me before closing a stale issue\"*\n- *\"when you triage PRs, leave the bot-authored ones alone\"*\n\nMagpie records it as an override for that skill (`/magpie-setup:setup override `).\nWorth sharing? Say *\"upstream this change to Magpie\"* \u2014 it makes the change generic and opens a PR to `apache/magpie` for you to review (`/magpie-setup:override-upstream`).\n\n## \ud83d\udcda More guides\n\nEach family can bring its own short guide, shown the first time you use it:\n\n- `contributor-growth` \u2014 `/magpie-setup:welcome-guide contributor-growth`\n- `issue` \u2014 `/magpie-setup:welcome-guide issue`\n- `mentoring` \u2014 `/magpie-setup:welcome-guide mentoring`\n- `pairing` \u2014 `/magpie-setup:welcome-guide pairing`\n- `pr-management` \u2014 `/magpie-setup:welcome-guide pr-management`\n- `release-management` \u2014 `/magpie-setup:welcome-guide release-management`\n- `repo-health` \u2014 `/magpie-setup:welcome-guide repo-health`\n- `security` \u2014 `/magpie-setup:welcome-guide security`\n- `setup` \u2014 `/magpie-setup:welcome-guide setup`\n- `utilities` \u2014 `/magpie-setup:welcome-guide utilities`\n\n## \ud83d\udc4b About this guide\n\n- **Continue** \u2014 show it again next time (three times at most)\n- **Dismiss** \u2014 hide it until the next Magpie upgrade\n- **Don't show again** \u2014 hide it for good; say *\"show the Magpie welcome again\"* to bring it back\n\nShow this again any time: `/magpie-setup:welcome-guide []`\n(`/magpie-setup-welcome-guide []` on a pinned snapshot).\n\n\ud83c\udf08 Prefer it in colour? Run this yourself \u2014 the `!` prefix runs it as a shell command:\n\n```text\n! PYTHONPATH=\".apache-magpie-local:$(git rev-parse --git-common-dir)/../.apache-magpie-local:$(git rev-parse --git-common-dir)/apache-magpie\" python3 -m setup_preflight.welcome show --family general --color=always\n```\n", "max_shown": 3, "reason": "first-run", "shown": 0 From dccf0a6f069edc06f30968e0b1112d0367e1bedc Mon Sep 17 00:00:00 2001 From: Jarek Potiuk Date: Tue, 20 Oct 2026 21:11:48 +0200 Subject: [PATCH 2/2] Apply review fixups for the release-management welcome guide - Renumber the first-run eval case to case-21, after the floor cases from #1673 and the repo-health and setup cases. - List release-trains.md under "Configure it": prepare, step 1 of the guide's own flow, stops without it. - Say where the distribution, approval and announcement backends are set. - Use concrete tailoring requests in "Make it yours". Generated-by: Claude Opus 5 --- .../setup/setup_preflight/guides/release-management.md | 7 ++++--- .../case-meta.json | 0 .../expected.json | 0 .../report.md | 2 +- .../state.json | 0 5 files changed, 5 insertions(+), 4 deletions(-) rename tools/skill-evals/evals/setup/preflight-floor/fixtures/{case-16-release-management-first-run => case-21-release-management-first-run}/case-meta.json (100%) rename tools/skill-evals/evals/setup/preflight-floor/fixtures/{case-16-release-management-first-run => case-21-release-management-first-run}/expected.json (100%) rename tools/skill-evals/evals/setup/preflight-floor/fixtures/{case-16-release-management-first-run => case-21-release-management-first-run}/report.md (70%) rename tools/skill-evals/evals/setup/preflight-floor/fixtures/{case-16-release-management-first-run => case-21-release-management-first-run}/state.json (100%) diff --git a/plugins/magpie-setup/skills/setup/setup_preflight/guides/release-management.md b/plugins/magpie-setup/skills/setup/setup_preflight/guides/release-management.md index c563d530b..0a9bc0806 100644 --- a/plugins/magpie-setup/skills/setup/setup_preflight/guides/release-management.md +++ b/plugins/magpie-setup/skills/setup/setup_preflight/guides/release-management.md @@ -28,8 +28,9 @@ Release skills use project-specific configuration: - โš™๏ธ **Release policy** โ€” `release-management-config.md` for planning, votes, announcements, archives, audit reports and KEYS - ๐Ÿ“ฆ **Build and staging** โ€” `release-build.md` for `rc-cut` and `verify-rc` - ๐Ÿ—ณ๏ธ **Approval roster** โ€” `pmc-roster.md` for `vote-tally` and `promote` +- ๐Ÿš† **Release trains** โ€” `release-trains.md` for `prepare` and `archive-sweep` -Choose the appropriate distribution, approval and announcement backends. +The distribution, approval and announcement backends are set in `release-management-config.md`. Configure personally with `/magpie-setup:setup config`. Team adoption with `/magpie-setup:setup adopt` is a maintainer decision. @@ -49,8 +50,8 @@ Talk to Magpie in plain language: Describe your release policy and preferred backend: -- *"use our project's configured release distribution backend"* -- *"use the approval mechanism and vote window in our release policy"* +- *"use a 96-hour vote window instead of 72"* +- *"always run the KEYS check before cutting an RC"* Review proposed configuration or override changes before applying them. Useful elsewhere? Ask *"upstream this change to Magpie"* to prepare a contribution for review. diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-16-release-management-first-run/case-meta.json b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-21-release-management-first-run/case-meta.json similarity index 100% rename from tools/skill-evals/evals/setup/preflight-floor/fixtures/case-16-release-management-first-run/case-meta.json rename to tools/skill-evals/evals/setup/preflight-floor/fixtures/case-21-release-management-first-run/case-meta.json diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-16-release-management-first-run/expected.json b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-21-release-management-first-run/expected.json similarity index 100% rename from tools/skill-evals/evals/setup/preflight-floor/fixtures/case-16-release-management-first-run/expected.json rename to tools/skill-evals/evals/setup/preflight-floor/fixtures/case-21-release-management-first-run/expected.json diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-16-release-management-first-run/report.md b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-21-release-management-first-run/report.md similarity index 70% rename from tools/skill-evals/evals/setup/preflight-floor/fixtures/case-16-release-management-first-run/report.md rename to tools/skill-evals/evals/setup/preflight-floor/fixtures/case-21-release-management-first-run/report.md index a313497a8..7603b5939 100644 --- a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-16-release-management-first-run/report.md +++ b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-21-release-management-first-run/report.md @@ -20,7 +20,7 @@ The pre-flight command printed: "code": "welcome", "facts": { "family": "release-management", - "guide": "# \ud83d\udc26 Magpie here \u2014 your release-management sidekick\n\nA one-minute tour, then straight back to what you asked for.\n\n## \ud83d\udd04 The typical flow\n\n1. \ud83d\udccb **Prepare** the release plan and version bump \u2014 *\"plan our next release\"*\n2. \ud83d\udd11 **Check KEYS** before RC signing \u2014 *\"sync the release signing key\"*\n3. \ud83d\udce6 **Cut an RC** and prepare signing/staging commands \u2014 *\"cut rc1 for this version\"*\n4. \u2705 **Verify the RC** before a vote \u2014 *\"verify the staged release candidate\"*\n5. \ud83d\uddf3\ufe0f **Draft the vote**, then tally results \u2014 *\"draft the vote email\"* / *\"tally the votes\"*\n6. \ud83d\ude80 **Promote** a release only after approval \u2014 *\"prepare promotion commands\"*\n7. \ud83d\udce3 **Draft the announcement**, then review archive cleanup \u2014 *\"draft the announcement\"*\n8. \ud83d\udcca **Audit** the completed release evidence \u2014 *\"prepare the release audit report\"*\n\nThese steps are guided workflows, not autonomous publishing.\nThe Release Manager keeps the signing key and runs signing and publication commands.\nVote and announcement emails are drafts, never automatically sent.\nReview and explicitly approve proposed external or repository changes.\n\n## \u2699\ufe0f Configure it\n\nRelease skills use project-specific configuration:\n\n- \u2699\ufe0f **Release policy** \u2014 `release-management-config.md` for planning, votes, announcements, archives, audit reports and KEYS\n- \ud83d\udce6 **Build and staging** \u2014 `release-build.md` for `rc-cut` and `verify-rc`\n- \ud83d\uddf3\ufe0f **Approval roster** \u2014 `pmc-roster.md` for `vote-tally` and `promote`\n\nChoose the appropriate distribution, approval and announcement backends.\nConfigure personally with `/magpie-setup:setup config`.\nTeam adoption with `/magpie-setup:setup adopt` is a maintainer decision.\n\n## \ud83d\udcac Just ask\n\nTalk to Magpie in plain language:\n\n- *\"prepare the release plan for our next version\"*\n- *\"check that my public signing key is in KEYS\"*\n- *\"give me the commands to cut and verify rc1\"*\n- *\"draft a vote email for this verified RC\"*\n- *\"tally the release vote and prepare the result draft\"*\n- *\"prepare promotion and announcement after the vote passes\"*\n- *\"review old release archives and generate an audit report\"*\n\n## \ud83c\udfa8 Make it yours\n\nDescribe your release policy and preferred backend:\n\n- *\"use our project's configured release distribution backend\"*\n- *\"use the approval mechanism and vote window in our release policy\"*\n\nReview proposed configuration or override changes before applying them.\nUseful elsewhere? Ask *\"upstream this change to Magpie\"* to prepare a contribution for review.\n\n## \ud83d\udc4b About this guide\n\n- **Continue** \u2014 show it again next time (three times at most)\n- **Dismiss** \u2014 hide it until the next Magpie upgrade\n- **Don't show again** \u2014 hide it for good; say *\"show the release-management welcome again\"* to bring it back\n\nShow this again any time: `/magpie-setup:welcome-guide release-management`\n(`/magpie-setup-welcome-guide release-management` on a pinned snapshot).\n\n\ud83c\udf08 Prefer it in colour? Run this yourself \u2014 the `!` prefix runs it as a shell command:\n\n```text\n! PYTHONPATH=\".apache-magpie-local:$(git rev-parse --git-common-dir)/../.apache-magpie-local:$(git rev-parse --git-common-dir)/apache-magpie\" python3 -m setup_preflight.welcome show --family release-management --color=always\n```\n", + "guide": "# \ud83d\udc26 Magpie here \u2014 your release-management sidekick\n\nA one-minute tour, then straight back to what you asked for.\n\n## \ud83d\udd04 The typical flow\n\n1. \ud83d\udccb **Prepare** the release plan and version bump \u2014 *\"plan our next release\"*\n2. \ud83d\udd11 **Check KEYS** before RC signing \u2014 *\"sync the release signing key\"*\n3. \ud83d\udce6 **Cut an RC** and prepare signing/staging commands \u2014 *\"cut rc1 for this version\"*\n4. \u2705 **Verify the RC** before a vote \u2014 *\"verify the staged release candidate\"*\n5. \ud83d\uddf3\ufe0f **Draft the vote**, then tally results \u2014 *\"draft the vote email\"* / *\"tally the votes\"*\n6. \ud83d\ude80 **Promote** a release only after approval \u2014 *\"prepare promotion commands\"*\n7. \ud83d\udce3 **Draft the announcement**, then review archive cleanup \u2014 *\"draft the announcement\"*\n8. \ud83d\udcca **Audit** the completed release evidence \u2014 *\"prepare the release audit report\"*\n\nThese steps are guided workflows, not autonomous publishing.\nThe Release Manager keeps the signing key and runs signing and publication commands.\nVote and announcement emails are drafts, never automatically sent.\nReview and explicitly approve proposed external or repository changes.\n\n## \u2699\ufe0f Configure it\n\nRelease skills use project-specific configuration:\n\n- \u2699\ufe0f **Release policy** \u2014 `release-management-config.md` for planning, votes, announcements, archives, audit reports and KEYS\n- \ud83d\udce6 **Build and staging** \u2014 `release-build.md` for `rc-cut` and `verify-rc`\n- \ud83d\uddf3\ufe0f **Approval roster** \u2014 `pmc-roster.md` for `vote-tally` and `promote`\n- \ud83d\ude86 **Release trains** \u2014 `release-trains.md` for `prepare` and `archive-sweep`\n\nThe distribution, approval and announcement backends are set in `release-management-config.md`.\nConfigure personally with `/magpie-setup:setup config`.\nTeam adoption with `/magpie-setup:setup adopt` is a maintainer decision.\n\n## \ud83d\udcac Just ask\n\nTalk to Magpie in plain language:\n\n- *\"prepare the release plan for our next version\"*\n- *\"check that my public signing key is in KEYS\"*\n- *\"give me the commands to cut and verify rc1\"*\n- *\"draft a vote email for this verified RC\"*\n- *\"tally the release vote and prepare the result draft\"*\n- *\"prepare promotion and announcement after the vote passes\"*\n- *\"review old release archives and generate an audit report\"*\n\n## \ud83c\udfa8 Make it yours\n\nDescribe your release policy and preferred backend:\n\n- *\"use a 96-hour vote window instead of 72\"*\n- *\"always run the KEYS check before cutting an RC\"*\n\nReview proposed configuration or override changes before applying them.\nUseful elsewhere? Ask *\"upstream this change to Magpie\"* to prepare a contribution for review.\n\n## \ud83d\udc4b About this guide\n\n- **Continue** \u2014 show it again next time (three times at most)\n- **Dismiss** \u2014 hide it until the next Magpie upgrade\n- **Don't show again** \u2014 hide it for good; say *\"show the release-management welcome again\"* to bring it back\n\nShow this again any time: `/magpie-setup:welcome-guide release-management`\n(`/magpie-setup-welcome-guide release-management` on a pinned snapshot).\n\n\ud83c\udf08 Prefer it in colour? Run this yourself \u2014 the `!` prefix runs it as a shell command:\n\n```text\n! PYTHONPATH=\".apache-magpie-local:$(git rev-parse --git-common-dir)/../.apache-magpie-local:$(git rev-parse --git-common-dir)/apache-magpie\" python3 -m setup_preflight.welcome show --family release-management --color=always\n```\n", "max_shown": 3, "reason": "first-run", "shown": 0 diff --git a/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-16-release-management-first-run/state.json b/tools/skill-evals/evals/setup/preflight-floor/fixtures/case-21-release-management-first-run/state.json similarity index 100% rename from tools/skill-evals/evals/setup/preflight-floor/fixtures/case-16-release-management-first-run/state.json rename to tools/skill-evals/evals/setup/preflight-floor/fixtures/case-21-release-management-first-run/state.json