Gentleman-Programming/release

Wann verwenden

Verwenden Sie diese Fertigkeit, wenn Sie ein gentle-pi Release vorbereiten, veröffentlichen oder überprüfen.

Harte Regeln

• Veröffentlichen Sie gentle-pi nicht über npm von einem lokalen Rechner aus.
• npm-Veröffentlichungen MÜSSEN über den GitHub Actions Workflow .github/workflows/publish.yml erfolgen, damit Provenienz, Umgebungsschutz und Registry-Anmeldeinformationen von GitHub kontrolliert werden.
• Lösen Sie die vertrauenswürdige Workflow-Definition vom geschützten Standard-main aus, niemals von einem Release-Tag. Die einzige Eingabe ist das genaue annotierte Versionstag.
• Verwenden Sie einen sauberen Arbeitsbereich für Release-Commits. Packen Sie keine unzusammenhängenden lokalen Dateien oder Arbeitsartefakte ein.
• Überprüfungsergebnisse sind informativ. Die Release-Auslieferung folgt der üblichen Repository-Richtlinie und darf nicht durch RDD blockiert, autorisiert oder umgeschrieben werden.
• Leiten Sie das Ziel des Release-Tags niemals vom lokalen HEAD ab; verwenden Sie den frisch geholten origin/main Commit und die normalen Release-Sicherheitsmechanismen des Repositorys.
• Überspringen Sie niemals die Paketüberprüfung. Der Publish-Workflow führt die Überprüfung erneut durch, aber die lokale Validierung sollte vor dem Taggen trotzdem bestanden werden.

Release-Verfahren

1. Zustand prüfen

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

2. Den Release-Commit vorbereiten

   • Nur beabsichtigte Änderungen anwenden.
   • package.json auf die nächste Semver-Version erhöhen.
   • Lockfile-Änderungen nur dann einbeziehen, wenn sich die Abhängigkeitsauflösung tatsächlich geändert hat.

3. Lokal überprüfen

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

   npm pack --dry-run überprüft Paketinhalt und Lifecycle-Skripte, ohne einen Veröffentlichungspfad zu betreten.

4. Committen und pushen

   git add <beabsichtigte-dateien>
   git commit -m "<typ(bereich): release-bereite änderung>"
   git push origin HEAD:main
   git fetch origin main --tags
   

5. Das genaue Versionstag erstellen und überprüfen

   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 "<release-notes>"
   

   Erstellen Sie kein Tag neu und überschreiben Sie keine vorhandene Version. Das Tag-Ziel stammt vom frisch geholten unveränderlichen origin/main Commit, nicht von einem lokalen Branch.

6. npm über GitHub Actions veröffentlichen

   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}"
   

   Die Workflow-Definition kommt immer vom geschützten Standard-main. Sie akzeptiert nur ein genaues vSemVer-Tag, holt das entfernte annotierte Tag und das aktuelle entfernte main, und erfordert, dass der entpackte Tag-Commit, der Dispatch/Main-Workflow-Commit, der Checkout und die package.json-Version übereinstimmen. Sie fragt das entfernte Tag und main unmittelbar vor der npm-Veröffentlichung erneut ab, leitet das dist-tag intern ab und verwendet vertrauenswürdiges OIDC mit Provenienz.

   Beobachten Sie den Lauf und brechen Sie das Release ab, wenn er fehlschlägt:

   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. npm überprüfen

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

Fehlerbehandlung

• Ein Publikationsfehler wird gemäß der üblichen Repository-Richtlinie behandelt. Er öffnet oder ändert keinen Überprüfungszweig.

• Versuchen Sie niemals npm publish lokal und wiederholen Sie es nicht. Lösen Sie den Vorgang vom vertrauenswürdigen main erneut aus, nur wenn das gleiche Tag immer noch auf das aktuelle entfernte main zeigt und der Fehler ausschließlich auf die Veröffentlichung zurückzuführen ist.

• Wenn das entfernte main voranschreitet, verschieben oder erstellen Sie das vorhandene Tag nicht neu. Bereiten Sie einen neuen Release-Commit / eine neue Version vor und erstellen Sie ein neues annotiertes Versionstag.

• Wenn der Workflow fehlschlägt, überprüfen Sie die Logs mit:

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

• Wenn die npm-Überprüfung nach einem erfolgreichen Workflow kurzzeitig veraltet ist, überprüfen Sie zuerst die genaue Version (npm view gentle-pi@<version> version), bevor Sie annehmen, dass die Veröffentlichung fehlgeschlagen ist.

Ausgabekontrakt

Berichten Sie:

• Commit SHA, der auf main gepusht wurde.
• Genauer Versionstag und sein entpackter Commit SHA.
• GitHub Release URL.
• Veröffentlichungs-Workflow Run URL und Ergebnis.
• Genaue npm-Version und das vom Workflow abgeleitete dist-tag (latest, beta oder next).
• Alle verbleibenden Folgeaktionen oder Warnungen.