Que fait gh-release ?
Bump, changelog, tag, push, watch.
Les commandes ci-dessous écrivent ~/.claude/skills/gh-release/scripts/ en entier. Exécutez-les exactement comme écrit - conservez le ~ en tête et ne l'étendez pas. Une règle de permission correspond à la chaîne de commande littérale, donc /home/<vous>/.claude/... (tilde étendu), python3 ~/..., un chemin relatif, et un cd préalable sont chacun une chaîne différente, et chacun redemande une permission. Un chemin tilde n'est pas "le chemin absolu écrit de manière informelle" - pour une règle de permission, il est le chemin.
Deux choses font échouer les releases, et les deux se produisent avant que le tag n'existe :
- Réinventer un bump que le dépôt automatise déjà. Une modification manuelle touche les fichiers que la propre tâche du dépôt aurait gérés, manque ceux qu'elle connaît, et ignore sa vérification.
- Un tag qui ne déclenche rien. Cela ressemble exactement à une file d'attente CI lente, et vous le découvrez vingt minutes plus tard.
Les étapes 1 et 3 existent pour attraper ces problèmes.
0. Décider la version
Lisez les tags (git tag --sort=-v:refname | head -5) pour connaître le format du dépôt (v1.2.3 vs 1.2.3) et la version actuelle. Si l'utilisateur a nommé une version, utilisez-la. Sinon, proposez-en une à partir des commits depuis le dernier tag - un changement cassant est majeur, feat: est mineur, sinon correctif - et dites laquelle et pourquoi.
Refusez de continuer si l'arbre de travail est sale, si HEAD est détaché, ou si la branche est en retard sur son dépôt distant. Publier du travail non commité produit un tag que personne ne peut reproduire.
1. Utiliser le mécanisme de release propre au dépôt
Regardez toujours avant de faire quoi que ce soit à la main :
~/.claude/skills/gh-release/scripts/versiontool.py discover
Il rapporte les compétences du projet, les tâches mise, les scripts npm, les cibles Make, les recettes just, les entrées scripts/-bin/, et les configurations d'outils (cargo-release, bumpversion, release-please, git-cliff). Priorité :
kind=project-skill - arrêtez de lire cette compétence et suivez celle-là. C'est la propre procédure du dépôt et elle sait des choses que cette compétence générique ne peut pas savoir.
Une tâche ou un script (kind=mise-task|npm-script|make-target|just-recipe|script) - lisez-le avant de l'exécuter, puis exécutez-le. Vous devez savoir ce qu'il couvre pour ne pas dupliquer ou sauter du travail. Les tâches typiques font une partie mais pas tout : bump, mise à jour du changelog, vérification, commit, tag, push. Notez lesquelles, puis ne faites que le reste.
Beaucoup prennent la version nue et ajoutent le préfixe elles-mêmes (mise run release 0.13.0 en taguant v0.13.0), donc ne passez pas un tag là où une version est attendue. Si elle a --dry-run, utilisez-la d'abord et montrez le plan à l'utilisateur.
Une configuration d'outil sans tâche - utilisez la propre commande de cet outil (cargo release <version>, bump-my-version bump ...), pas une modification manuelle.
result=none - seulement alors, retombez sur l'étape 2.
2. Solution de repli : trouver tous les endroits où vit la version
Uniquement lorsque l'étape 1 n'a rien trouvé.
~/.claude/skills/gh-release/scripts/versiontool.py locations <version-actuelle>
Il recherche la chaîne de version littérale, pas le mot "version". Mesuré sur un dépôt réel : une recherche par clé version a trouvé 5 fichiers, la chaîne littérale en a trouvé 8. Les fichiers manquants orthographiaient la clé "version-name" (métadonnées GNOME) et "Version" (Plasma). Tout ce que vous ratez expédie un binaire qui rapporte la mauvaise version.
La sortie est classifiée : edit (modifiez-le), regenerate (fichier de verrouillage - exécutez la commande de l'indice, ne modifiez jamais manuellement, sinon --locked échoue en CI), changelog (étape 4).
Ensuite, vérifiez aussi la version précédente - une correspondance là-bas est un fichier oublié lors de la dernière release et obsolète depuis. Corrigez-le dans celle-ci.
3. Pré-vol du tag
~/.claude/skills/gh-release/scripts/relwatch.py preflight <tag>
Il lit .github/workflows/*.yml, extrait chaque motif on.push.tags, et vous dit si votre tag correspond à l'un d'eux et si ce workflow semble créer une release. result=NO_MATCH signifie que pousser le tag ne fait rien du tout.
Exécutez ceci avant de commiter, quand changer le tag est gratuit.
Confirmez également visuellement que l'étape de release du workflow utilise le tag que vous allez pousser. De nombreux workflows ne vérifient pas que le tag correspond à la version dans le code, donc une discordance produit une release dont les binaires rapportent la mauvaise version, silencieusement et avec une CI verte.
4. Changelog
Si la tâche de l'étape 1 promeut elle-même le changelog, laissez-la faire et passez à l'étape 5.
Tenir un journal des modifications (il y a un en-tête ## [Unreleased]) : promouvez-le.
## [Unreleased]devient## [X.Y.Z] - YYYY-MM-DD- ajoutez un nouvel en-tête vide
## [Unreleased]au-dessus - mettez à jour les définitions de liens en bas, y compris la nouvelle base du lien de comparaison
[Unreleased]
Pas de changelog, ou pas de section Unreleased : écrivez l'entrée à partir des commits depuis le dernier tag, regroupée comme le fichier les regroupe déjà. Correspond exactement à la voix existante - si les entrées sont des lignes uniques, écrivez des lignes uniques ; si ce sont des paragraphes avec des titres en gras, écrivez cela.
Dans les deux cas : décrivez ce qui a changé pour un utilisateur du projet, pas ce que vous avez fait au dépôt.
Appliquez la compétence unslop à chaque entrée. Un changelog est lu pendant des années, par des personnes qui décident de mettre à jour ou non. "Diverses améliorations et corrections de bugs" est pire qu'aucune entrée ; de même qu'une entrée qui reformule le sujet du commit en mots plus longs. Les marqueurs spécifiques au document sont listés dans l'étape 5 de docs-update/SKILL.md et s'appliquent ici inchangés : pas de préambule inutile, pas d'intensificateurs vides, pas de réserve quand la réponse est définitive.
5. Vérifier avant de taguer
~/.claude/skills/gh-release/scripts/versiontool.py verify <ancienne-version> # doit afficher result=clean
Exécutez ceci même si une tâche du dépôt a fait le bump. Un outil de bump écrit il y a six mois ne connaît pas le fichier que quelqu'un a ajouté la semaine dernière, et c'est exactement ainsi qu'une version devient obsolète dans un coin de l'arborescence. L'historique du changelog est ignoré ; seuls les fichiers modifiables comptent.
Ensuite, exécutez la porte du projet (build, test, lint). Un tag pointant vers un commit rouge doit être supprimé et recréé, et supprimer un tag poussé est gênant pour quiconque l'a déjà récupéré.
6. Commit, tag, push
Sautez ce que la tâche de l'étape 1 a déjà fait. Si elle a commité, tagué et poussé, allez directement à l'étape 7.
Sinon : un commit pour la release, sujet préfixé par le nom de la branche selon ~/.claude/CLAUDE.md. Le bump et le changelog appartiennent au même commit ; ils ne forment qu'un changement.
git commit -m "[<branche>] chore(release): <version>"
git tag -a <tag> -m "<tag>"
git push && git push origin <tag>
Poussez le commit avant le tag. Un tag qui arrive en premier peut démarrer une build contre un commit que le dépôt distant n'a pas encore.
Notez l'heure du push ; elle borne la surveillance.
7. Surveiller jusqu'à ce que la release existe
~/.claude/skills/gh-release/scripts/relwatch.py watch <tag> --timeout 1800
| Résultat | Signification |
|---|---|
released url=... | terminé |
ci_failed run=... conclusion=... | étape 8 |
no_run | rien n'a été déclenché. Le tag ne correspond à aucun motif - exécutez preflight |
still_running | pas un échec. Surveillez à nouveau |
Une CI verte n'est pas une release : l'étape de publication peut être en retard sur la build, donc le watcher continue d'attendre jusqu'à ce que l'objet Release existe réellement.
Même règle de sous-agent que babysit-pr : une seule surveillance dans un seul appel Bash (--timeout 540) est moins coûteuse en ligne ; déléguez seulement quand l'attente s'étend sur plusieurs appels. Ne vous arrêtez pas avant que la release existe ou que vous ayez un blocage.
8. Quand la CI échoue après le tag
Le tag est erroné, donc retirez-le plutôt que de le corriger :
git push --delete origin <tag>
git tag -d <tag>
Corrigez, puis refaites à partir de l'étape 5 avec le même numéro de version. Ne passez pas à une version supérieure pour contourner un échec : une version que personne n'a jamais publiée ne vaut pas la peine d'être brûlée, et l'écart invite quelqu'un à chercher la release manquante.
Si le tag est public depuis un certain temps, ou si une release partielle existe, dites-le et laissez l'utilisateur choisir entre le supprimer et publier un correctif par-dessus.
9. Rapport
Lien PR/compare, le tag, l'URL de la release, ce qui a changé, et chaque fichier modifié. Si quelque chose a été laissé à l'utilisateur, nommez-le.