Was macht gh-release?
Bump, Changelog, Tag, Push, Überwachen.
Die untenstehenden Befehle geben ~/.claude/skills/gh-release/scripts/ vollständig aus. Führe sie genau wie geschrieben aus – behalte das führende ~ bei und erweitere es nicht. Eine Berechtigungsregel erwartet die literale Befehlszeichenfolge, daher sind /home/<you>/.claude/... (die Tilde erweitert), python3 ~/..., ein relativer Pfad oder ein vorheriger cd-Befehl jeweils andere Zeichenfolgen, die erneut zur Bestätigung auffordern. Ein Tilden-Pfad ist nicht „der absolute Pfad informell geschrieben“ – für eine Berechtigungsregel ist er der Pfad.
Zwei Dinge lassen Releases schiefgehen, und beide passieren bevor der Tag existiert:
- Das Neuerfinden eines Bumps, den das Repo bereits automatisiert. Eine manuelle Bearbeitung berührt Dateien, die der eigene Task des Repos behandelt hätte, übersieht die, die er kennt, und überspringt dessen Kontrollpunkt.
- Ein Tag, der nichts auslöst. Es sieht genauso aus wie eine langsame CI-Warteschlange, und zwanzig Minuten später stellst du fest, dass nichts passiert ist.
Die Schritte 1 und 3 dienen dazu, diese Fehler abzufangen.
0. Version festlegen
Lese die Tags (git tag --sort=-v:refname | head -5), um das Format des Repos (v1.2.3 vs 1.2.3) und die aktuelle Version zu erfahren. Wenn der Benutzer eine Version genannt hat, verwende sie. Andernfalls schlage eine aus den Commits seit dem letzten Tag vor – ein Breaking Change ist Major, feat: ist Minor, sonst Patch – und gib an, welche und warum.
Verweigere die Fortsetzung bei einem unsauberen Arbeitsverzeichnis, einem detached HEAD oder einem Branch, der hinter dem Remote liegt. Das Veröffentlichen ungesicherter Arbeit erzeugt einen Tag, den niemand reproduzieren kann.
1. Die eigenen Release-Mechanismen des Repos nutzen
Schau immer zuerst nach, bevor du etwas manuell machst:
~/.claude/skills/gh-release/scripts/versiontool.py discover
Es meldet Projekt-Skills, Mise-Tasks, npm-Skripte, Make-Targets, Just-Rezepte, scripts/-bin/-Einträge und Tool-Konfigurationen (cargo-release, bumpversion, release-please, git-cliff). Priorität:
kind=project-skill – höre auf, diese Skill zu lesen, und folge jener. Es ist das eigene Verfahren des Repos und es weiß Dinge, die diese generische Skill nicht wissen kann.
Ein Task oder Skript (kind=mise-task|npm-script|make-target|just-recipe|script)
- lies es, bevor du es ausführst, dann führe es aus. Du musst wissen, was es abdeckt, damit du keine Arbeit doppelt machst oder überspringst. Typische Tasks erledigen einige, aber nicht alle der folgenden Schritte: Bump, Changelog-Promotion, Kontrollpunkt, Commit, Tag, Push. Merke dir, welche, und erledige nur den Rest.
Viele erwarten die reine Version und fügen das Präfix selbst hinzu (mise run release 0.13.0 taggt v0.13.0), also übergib keinen Tag, wo eine Version erwartet wird. Wenn es --dry-run hat, verwende es zuerst und zeige dem Benutzer den Plan.
Eine Tool-Konfiguration ohne Task – verwende den eigenen Befehl des Tools (cargo release <version>, bump-my-version bump ...), nicht eine manuelle Bearbeitung.
result=none – erst dann falle auf Schritt 2 zurück.
2. Fallback: Jeden Ort finden, an dem die Version lebt
Nur wenn Schritt 1 nichts gefunden hat.
~/.claude/skills/gh-release/scripts/versiontool.py locations <aktuelle-version>
Es sucht nach der literalen Versionszeichenfolge, nicht nach dem Wort „version“. Gemessen an einem echten Repo: Eine Suche nach dem version-Schlüssel fand 5 Dateien, die literale Zeichenfolge fand 8. Die Fehlenden hatten den Schlüssel "version-name" (GNOME-Metadaten) und "Version" (Plasma). Alles, was du übersiehst, liefert eine Binärdatei aus, die die falsche Version meldet.
Die Ausgabe ist klassifiziert: edit (ändern), regenerate (Lockfile – führe den Befehl des Hinweises aus, niemals manuell bearbeiten, sonst schlägt --locked in CI fehl), changelog (Schritt 4).
Überprüfe dann auch die vorherige Version – ein Treffer dort ist eine Datei, die im letzten Release übersehen wurde und seitdem veraltet ist. Korrigiere sie in diesem Release.
3. Preflight für den Tag
~/.claude/skills/gh-release/scripts/relwatch.py preflight <tag>
Es liest .github/workflows/*.yml, extrahiert jedes on.push.tags-Muster und teilt dir mit, ob dein Tag zu einem passt und ob dieser Workflow aussieht, als ob er einen Release erstellt. result=NO_MATCH bedeutet, dass das Pushen des Tags überhaupt nichts bewirkt.
Führe dies vor dem Commit aus, während das Ändern des Tags kostenlos ist.
Überprüfe auch mit eigenen Augen, dass der Release-Schritt des Workflows den Tag verwendet, den du gleich pushen wirst. Viele Workflows prüfen nicht, ob der Tag mit der Version im Code übereinstimmt, sodass eine Diskrepanz einen Release erzeugt, dessen Binärdateien die falsche Version melden – still und mit grünem CI.
4. Changelog
Wenn der Task aus Schritt 1 das Changelog selbst promoted, lass es ihn tun und springe zu Schritt 5.
Keep a Changelog (es gibt eine ## [Unreleased]-Überschrift): promote sie.
## [Unreleased]wird zu## [X.Y.Z] - YYYY-MM-DD- füge eine frische leere
## [Unreleased]darüber ein - aktualisiere die Link-Definitionen am Ende, einschließlich der neuen Basis des
[Unreleased]-Vergleichslinks
Kein Changelog oder kein Unreleased-Abschnitt: schreibe den Eintrag aus den Commits seit dem letzten Tag, gruppiert, wie die Datei sie bereits gruppiert. Passe die vorhandene Stimme genau an – wenn Einträge Einzeiler sind, schreibe Einzeiler; wenn sie Prosa mit fettgedruckten Einleitungen sind, schreibe so.
Beschreibe in beiden Fällen, was sich für einen Benutzer des Projekts geändert hat, nicht was du mit dem Repo gemacht hast.
Wende die unslop-Skill auf jeden Eintrag an. Ein Changelog wird jahrelang von Menschen gelesen, die entscheiden, ob sie upgraden sollen. „Verschiedene Verbesserungen und Fehlerbehebungen“ ist schlimmer als kein Eintrag; ebenso ein Eintrag, der den Commit-Betreff mit längeren Worten wiederholt. Die dokumentspezifischen Anzeichen sind in docs-update/SKILL.md Schritt 5 aufgeführt und gelten hier unverändert: kein Räuspern, keine leeren Verstärker, keine Absicherung, wo die Antwort eindeutig ist.
5. Vor dem Tag verifizieren
~/.claude/skills/gh-release/scripts/versiontool.py verify <alte-version> # muss result=clean ausgeben
Führe dies auch aus, wenn ein Repo-Task den Bump durchgeführt hat. Ein Bumper, der vor sechs Monaten geschrieben wurde, weiß nichts von der Datei, die letzte Woche jemand hinzugefügt hat, und genau so wird eine Version in einer Ecke des Baums veraltet. Die Changelog-Historie wird ignoriert; nur bearbeitbare Dateien zählen.
Führe dann die Projektprüfung aus (Build, Test, Lint). Ein Tag, der auf einen roten Commit zeigt, muss gelöscht und neu geschnitten werden, und das Löschen eines gepushten Tags ist umständlich für jeden, der ihn bereits geholt hat.
6. Commit, Tag, Push
Überspringe, was der Task aus Schritt 1 bereits erledigt hat. Wenn er committed, getaggt und gepusht hat, gehe direkt zu Schritt 7.
Andernfalls: ein Commit für den Release, Betreff mit dem Branchnamen gemäß ~/.claude/CLAUDE.md präfigiert. Der Bump und das Changelog gehören in denselben Commit; sie sind eine Änderung.
git commit -m "[<branch>] chore(release): <version>"
git tag -a <tag> -m "<tag>"
git push && git push origin <tag>
Pushe den Commit vor dem Tag. Ein Tag, der zuerst ankommt, kann einen Build gegen einen Commit starten, den das Remote noch nicht hat.
Merke dir die Push-Zeit; sie begrenzt die Überwachung.
7. Überwachen, bis der Release existiert
~/.claude/skills/gh-release/scripts/relwatch.py watch <tag> --timeout 1800
| Ergebnis | Bedeutung |
|---|---|
released url=... | erledigt |
ci_failed run=... conclusion=... | Schritt 8 |
no_run | Es wurde nichts ausgelöst. Der Tag passte zu keinem Muster – führe preflight aus |
still_running | kein Fehler. Überwache erneut |
Grünes CI ist kein Release: Der Veröffentlichungsschritt kann dem Build hinterherhinken, also wartet der Überwacher, bis das Release-Objekt tatsächlich existiert.
Gleiche Subagentenregel wie bei babysit-pr: eine einzelne Überwachung innerhalb eines Bash-Aufrufs (--timeout 540) ist günstiger inline; delegiere nur, wenn die Wartezeit mehrere Aufrufe umfasst. Höre nicht auf, bevor der Release existiert oder du einen Blocker hast.
8. Wenn CI nach dem Tag fehlschlägt
Der Tag ist falsch, also ziehe ihn zurück, anstatt ihn zu flicken:
git push --delete origin <tag>
git tag -d <tag>
Behebe den Fehler, dann schneide ab Schritt 5 mit der gleichen Versionsnummer neu. Erhöhe nicht, um an einem Fehler vorbeizukommen: Eine Version, die nie veröffentlicht wurde, ist es nicht wert, verbrannt zu werden, und die Lücke lädt jemanden ein, nach dem fehlenden Release zu suchen.
Wenn der Tag eine Weile öffentlich war oder ein Teil-Release existiert, sage dies und lass den Benutzer zwischen Löschen und einem Patch darüber wählen.
9. Bericht
PR-/Vergleichs-Link, der Tag, die Release-URL, was sich geändert hat, und jede erhöhte Datei. Wenn etwas für den Benutzer übrig geblieben ist, benenne es.