This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow-steward.git
The following commit(s) were added to refs/heads/main by this push:
new 25e1664 docs(setup-steward): make upgrade re-link every chosen-family
skill (#162)
25e1664 is described below
commit 25e166400e5b81e1209ff7a5d6d39506494ab4b4
Author: Jarek Potiuk <[email protected]>
AuthorDate: Fri May 15 04:12:50 2026 +0200
docs(setup-steward): make upgrade re-link every chosen-family skill (#162)
`upgrade.md` Step 6 previously only added new family-member
skills and reconciled stale symlinks; it left existing-but-
broken or missing-but-should-be-there symlinks for the chosen
families untouched. Restructure into two passes: pass 1
unconditionally ensures every framework skill in a chosen
family has a valid symlink (create or repair), pass 2
reconciles stale symlinks as before. Add `↻` to the upgrade
summary output to distinguish repaired from newly-created
links, and tighten the `skill-families:` arg-table entry in
`SKILL.md` to match.
Generated-by: Claude Code (Claude Opus 4.7)
---
.claude/skills/setup-steward/SKILL.md | 2 +-
.claude/skills/setup-steward/upgrade.md | 51 +++++++++++++++++++++++++--------
2 files changed, 40 insertions(+), 13 deletions(-)
diff --git a/.claude/skills/setup-steward/SKILL.md
b/.claude/skills/setup-steward/SKILL.md
index fb9b8b4..5b0b927 100644
--- a/.claude/skills/setup-steward/SKILL.md
+++ b/.claude/skills/setup-steward/SKILL.md
@@ -270,7 +270,7 @@ first, then continue.
|---|---|
| `from:<git-ref>` / `from:<version>` | Adopt or upgrade from a specific
framework ref or version. Used during `adopt` (overrides the user prompt) and
`upgrade` (overrides the committed lock for *this run only* — does NOT update
the committed lock). |
| `method:<git-branch\|git-tag\|svn-zip>` | Pick the install method
explicitly. Default during `adopt`: prompt the user. |
-| `skill-families:<list>` | Comma-separated families to symlink (`security`,
`pr-management`). Default on `adopt`: prompt. Default on `upgrade`: re-symlink
the families currently linked. |
+| `skill-families:<list>` | Comma-separated families to symlink (`security`,
`pr-management`). Default on `adopt`: prompt. Default on `upgrade`: read the
families list from `<committed-lock>` / `<local-lock>` and **ensure every
framework skill in those families has a valid symlink** — create or repair
missing / broken symlinks, not just add new ones. |
| `--purge-overrides` | *(unadopt only)* Also `git rm -r`
`.apache-steward-overrides/`. Default: preserve. |
| `dry-run` | Show what the skill would do without writing anything. |
diff --git a/.claude/skills/setup-steward/upgrade.md
b/.claude/skills/setup-steward/upgrade.md
index dc11b48..680bf1a 100644
--- a/.claude/skills/setup-steward/upgrade.md
+++ b/.claude/skills/setup-steward/upgrade.md
@@ -158,17 +158,41 @@ pattern-matching.
## Step 6 — Refresh framework-skill symlinks
-Walk `<adopter-skills-dir>` looking for stale symlinks that
-point at framework skills no longer in the new snapshot
-(rename, removal). For each:
-
-- If renamed (the framework documented a rename in its
- release notes), offer to re-symlink to the new name.
-- If removed, offer to remove the stale symlink.
-
-Then walk the new snapshot for any new framework skills in
-the families the adopter previously picked, and offer to
-symlink them in.
+Read the chosen skill families from `<committed-lock>`
+(falling back to `<local-lock>` if the committed lock is
+silent on families). The post-upgrade state must be:
+*every framework skill in the new snapshot that belongs to
+a chosen family has a valid symlink in
+`<adopter-skills-dir>`*, and *no symlink points at a
+framework skill that no longer exists in the snapshot*.
+
+Run two passes:
+
+1. **Ensure every family-member skill is linked.** For each
+ framework skill in the new snapshot that belongs to a
+ chosen family, check `<adopter-skills-dir>/<skill>`:
+ - If the symlink exists and points at the matching
+ snapshot path, leave it alone.
+ - If it's missing, create it.
+ - If it exists but is broken (target gone, points at the
+ wrong path), repair it.
+
+ Do this unconditionally — do not skip skills whose
+ symlinks "should" already be there. A contributor who
+ ran `git clean -fdx`, blew away `<adopter-skills-dir>` by
+ accident, or merged a branch that removed the symlinks
+ gets the full set restored without per-symlink re-
+ prompting. The aggregated list of created / repaired
+ links is reported in the upgrade summary (Step 8 output
+ block, under the `+` and `↻` rows).
+
+2. **Reconcile stale symlinks.** Walk
+ `<adopter-skills-dir>` looking for symlinks that point
+ at framework skills no longer in the new snapshot
+ (rename, removal). For each:
+ - If renamed (the framework documented a rename in its
+ release notes), offer to re-symlink to the new name.
+ - If removed, offer to remove the stale symlink.
For the double-symlinked convention, refresh both layers.
@@ -258,7 +282,10 @@ Drift remediated:
Symlinks:
✓ <list of unchanged symlinks>
- + <list of newly-symlinked framework skills>
+ + <list of newly-created symlinks (skill present in a chosen
+ family but missing from <adopter-skills-dir>)>
+ ↻ <list of repaired symlinks (existed but broken / pointing
+ at the wrong path)>
- <list of removed stale symlinks>
Overrides:
