Gentleman-Programming/release

Quand utiliser

Utilisez cette compétence lors de la préparation, de la publication ou de la vérification d'une version de gentle-pi.

Règles strictes

• Ne publiez pas gentle-pi sur npm depuis une machine locale.
• La publication npm DOIT passer par le workflow GitHub Actions .github/workflows/publish.yml afin que la provenance, la protection de l'environnement et les identifiants de registre soient contrôlés par GitHub.
• Déclenchez la définition de workflow de confiance depuis la branche protégée par défaut main, jamais depuis un tag de release. Son seul paramètre d'entrée est le tag de version annoté exact.
• Utilisez une arborescence de travail propre pour les commits de release. N'incluez pas de fichiers locaux non liés ou d'artefacts temporaires.
• Les résultats de vérification sont informatifs. La livraison de la release suit la politique de dépôt ordinaire et ne doit pas être bloquée, autorisée ou réécrite par RDD.
• N'inférez jamais la cible du tag de release depuis le HEAD local ; utilisez le commit fraîchement récupéré de origin/main et les protections de release normales du dépôt.
• Ne sautez jamais la vérification du package. Le workflow de publication exécute à nouveau la vérification, mais la validation locale doit toujours passer avant le taggage.

Procédure de release

1. Inspecter l'état

   git status --short
   git fetch origin main --tags
   git log --oneline --decorate --max-count=5 origin/main
   

2. Préparer le commit de release

   • Appliquez uniquement les modifications prévues.
   • Mettez à jour package.json vers la prochaine version sémantique.
   • Ne conservez les modifications du fichier de verrouillage (lockfile) que si la résolution des dépendances a réellement changé.

3. Vérifier localement

   pnpm test
   node scripts/verify-package-files.mjs
   npm pack --dry-run
   

   npm pack --dry-run vérifie le contenu du package et les scripts de cycle de vie sans effectuer de publication.

4. Commiter et pousser

   git add <fichiers-voulus>
   git commit -m "<type(scope): modification prête pour release>"
   git push origin HEAD:main
   git fetch origin main --tags
   

5. Créer et vérifier le tag de version exact

   version="$(node -p "require('./package.json').version")"
   tag="v${version}"
   release_sha="$(git rev-parse 'origin/main^{commit}')"
   
   test "$(git rev-parse 'HEAD^{commit}')" = "${release_sha}"
   test -z "$(git ls-remote --tags origin "refs/tags/${tag}")"
   
   git tag -a "${tag}" "${release_sha}" -m "gentle-pi ${tag}"
   test "$(git rev-parse "${tag}^{commit}")" = "${release_sha}"
   
   git fetch origin main
   test "$(git rev-parse 'origin/main^{commit}')" = "${release_sha}"
   git push origin "refs/tags/${tag}"
   
   git fetch --no-tags origin "refs/tags/${tag}"
   test "$(git rev-parse 'FETCH_HEAD^{commit}')" = "${release_sha}"
   
   gh release create "${tag}" \
     --repo Gentleman-Programming/gentle-pi \
     --verify-tag \
     --title "gentle-pi ${tag}" \
     --notes "<notes de release>"
   

   Ne retaguez pas et n'écrasez pas une version existante. La cible du tag provient du commit fraîchement récupéré et immuable de origin/main, pas d'une branche locale ambiante.

6. Publier sur npm via GitHub Actions

   version="$(node -p "require('./package.json').version")"
   tag="v${version}"
   gh workflow run publish.yml \
     --repo Gentleman-Programming/gentle-pi \
     --ref main \
     -f tag="${tag}"
   

   La définition du workflow provient toujours de la branche protégée par défaut main. Elle accepte un seul tag vSemVer exact, récupère le tag annoté distant et le main distant actuel, et exige que le commit du tag déroulé, le commit du workflow dispatch/main, le checkout et la version de package.json correspondent. Elle interroge à nouveau le tag distant et main immédiatement avant la publication npm, dérive le dist-tag en interne, et utilise OIDC de confiance avec provenance.

   Surveillez l'exécution et échouez la release si elle échoue :

   gh run list --repo Gentleman-Programming/gentle-pi --workflow publish.yml --limit 3
   gh run watch <run-id> --repo Gentleman-Programming/gentle-pi --exit-status
   

7. Vérifier npm

   npm view gentle-pi@<version> version --registry=https://registry.npmjs.org/
   npm dist-tag ls gentle-pi --registry=https://registry.npmjs.org/
   

Gestion des échecs

• Un échec de publication est traité selon la politique de dépôt ordinaire. Il ne rouvre ni ne modifie une lignée de revue.

• N'essayez jamais et ne retentez jamais npm publish localement. Redispatchez depuis main de confiance uniquement lorsque le même tag cible toujours le main distant actuel et que l'échec concernait uniquement la publication.

• Si le main distant avance, ne déplacez pas et ne recréez pas le tag existant. Préparez un nouveau commit/version de release et créez un nouveau tag de version annoté.

• Si le workflow échoue, inspectez les logs avec :

  gh run view <run-id> --repo Gentleman-Programming/gentle-pi --log
  

• Si la vérification npm est temporairement obsolète après un workflow réussi, vérifiez d'abord la version exacte (npm view gentle-pi@<version> version) avant de supposer que la publication a échoué.

Contrat de sortie

Rapportez :

• SHA du commit poussé sur main.
• Tag de version exact et son SHA de commit déroulé.
• URL de la release GitHub.
• URL de l'exécution du workflow de publication et conclusion.
• Version exacte npm et le dist-tag dérivé du workflow (latest, beta, ou next).
• Tout suivi ou avertissement restant.