Gentleman-Programming/release

使用時機

當您需要準備、發佈或驗證 gentle-pi 的版本時，請使用此技能。

嚴格規則

• 禁止從本地機器將 gentle-pi 發佈到 npm。
• npm 發佈必須透過 GitHub Actions 工作流程 .github/workflows/publish.yml 進行，以確保 provenance（來源證明）、環境保護與註冊表憑證由 GitHub 控制。
• 從受保護的預設分支 main 分派可信的工作流程定義，絕不從發佈標籤進行。其唯一的呼叫輸入是精確的標註版本標籤（annotated version tag）。
• 使用乾淨的工作目錄（worktree）進行發佈提交。不要打包不相關的本地檔案或暫存產物。
• 審查結果僅供參考。發佈交付遵循一般儲存庫政策，不得被 RDD（Review-Driven Development）阻止、授權或重寫。
• 絕不從本地 HEAD 推斷發佈標籤的目標；應使用剛擷取的 origin/main 提交與儲存庫正常的發佈保護機制。
• 絕不跳過套件驗證。發佈工作流程會再次執行驗證，但在打標籤前，本地驗證仍需通過。

發佈流程

1. 檢查狀態

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

2. 準備發佈提交

   • 僅套用預期的變更。
   • 將 package.json 中的版本號提升至下一個 semver 版本。
   • 除非相依性解析真的變動，否則不要包含 lockfile 的變更。

3. 本地驗證

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

   npm pack --dry-run 會驗證套件內容與生命週期腳本，但不會進入發佈路徑。

4. 提交與推送

   git add <預期檔案>
   git commit -m "<類型(範圍): 準備發佈的變更>"
   git push origin HEAD:main
   git fetch origin main --tags
   

5. 建立並驗證精確的版本標籤

   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 "<發佈說明>"
   

   不要重新打標籤或覆蓋已有的版本。標籤目標來自剛擷取的不可變 origin/main 提交，而不是外部的本地分支。

6. 透過 GitHub Actions 發佈 npm 套件

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

   工作流程定義始終來自受保護的預設分支 main。它只接受一個精確的 vSemVer 標籤，會擷取遠端標註標籤與目前遠端 main，並要求 peeled 標籤提交、分派/main 工作流程提交、檢出與 package.json 版本號都一致。它會在 npm 發佈前立即重新查詢遠端標籤與 main，內部推導 dist-tag，並使用受信任的 OIDC 與 provenance。

   監控工作流程執行，若失敗則停止發佈：

   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 發佈

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

失敗處理

• 發佈失敗應依照一般儲存庫政策處理。不會重新開啟或變更審查流程。

• 絕不嘗試或重試本機 npm publish。僅當同一個標籤仍指向目前遠端 main且失敗原因單純是發佈環節時，才從受信任的 main 重新分派。

• 如果遠端 main 已推進，不要移動或重新建立現有的標籤。請準備一個新的發佈提交/版本，並建立一個新的標註版本標籤。

• 如果工作流程失敗，請使用以下指令檢查日誌：

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

• 如果成功的工作流程後 npm 驗證暫時延遲，請先檢查確切版本號（npm view gentle-pi@<版本> version），再假設發佈失敗。

輸出合約

回報以下資訊：

• 推送至 main 的提交 SHA。
• 精確的版本標籤及其 peeled 提交 SHA。
• GitHub Release 網址。
• 發佈工作流程的執行網址與結果。
• npm 精確版本號與工作流程推導出的 dist-tag（latest、beta 或 next）。
• 任何剩餘的後續動作或警告。