juraj-blahunka/release

發布 simctlhouse

發布本儲存庫的 X.Y.Z 版本：包含經過公證的 tarball 的 GitHub Release，以及 tap 中的公式。 scripts/release.sh 負責建置、簽名、公證與打包；此技能處理上述環節之外的所有工作。 docs/how-to.md（「進行發布」）與 docs/decisions.md 中的 D27 說明了設計原理。

固定名稱：

項目	值
GitHub 儲存庫	juraj-blahunka/simctlhouse（遠端 origin）
Tap 簽出版本	../homebrew-tap，GitHub juraj-blahunka/homebrew-tap，作為 juraj-blahunka/tap 使用
Tap 中的公式	Formula/simctlhouse.rb
標籤	vX.Y.Z
Tarball	dist/simctlhouse-X.Y.Z-macos.tar.gz
發布說明	dist/release-notes-X.Y.Z.md（dist/ 已被 git 忽略）

除非另有說明，否則請在儲存庫根目錄下執行所有命令。 遇到第一個失敗即停止，報告失敗的內容及其輸出，並且不要繞過問題（不使用 --skip-notarize、--allow-dirty、--force 或 --no-verify）。

1. 選擇版本

使用使用者提供的版本。 否則提議一個版本並詢問：使用 git log --oneline $(git describe --tags --abbrev=0 2>/dev/null)..HEAD（若無標籤則列出所有提交）列出自最後一個標籤以來的變更，然後對 feat: 提交提升 minor 版本，對僅修復的提交提升 patch 版本。

2. 檢查先決條件

在變更任何內容之前，請檢查以下所有項目，並一次回報所有失敗：

git rev-parse --abbrev-ref HEAD                  # main
git status --porcelain --untracked-files=no      # 空白
git fetch origin && git status -sb | head -1     # 未落後於 origin/main
git ls-remote --tags origin "refs/tags/vX.Y.Z"   # 空白：該版本尚未發布
gh auth status                                   # 已登入
git -C ../homebrew-tap status --porcelain        # tap 存在且乾淨
git -C ../homebrew-tap pull --ff-only            # tap 為最新狀態

如果 origin 或 tap 缺失，請停止並告知使用者需要建立什麼；切勿自行建立 GitHub 儲存庫。 新的 tap 需要 GitHub 儲存庫 juraj-blahunka/homebrew-tap，複製到 ../homebrew-tap，並包含 Formula/ 目錄。

3. 提升版本號

如果 Sources/simctlhouse/SimctlHouse.swift 中的 version: 不是 X.Y.Z，則在此檔案中更改，執行 swift build 和 swift test，並僅提交該檔案：

git commit -m "chore: release X.Y.Z" Sources/simctlhouse/SimctlHouse.swift

4. 與使用者共同撰寫發布說明

根據自上次發布以來的變更起草說明：

git log --format='%h %s%n%b' $(git describe --tags --abbrev=0 2>/dev/null)..HEAD
git diff --stat $(git describe --tags --abbrev=0 2>/dev/null)..HEAD

閱讀提交記錄，對於主題不明確的提交，閱讀 diff 本身；說明應描述 CLI 和技能的使用者會注意到的內容，而非程式碼的變更方式。

• 以一兩句話說明發布的重點。

• 然後分節，省略空節：## 新增、## 變更、## 修復，以及 ## 破壞性變更（如果有任何會破壞腳本或代理的變更，例如重新命名的命令或旗標、變更的輸出、變更的退出碼）。

• 每項變更一個項目符號，命令或旗標使用反引號，例如 simctlhouse skill install。

• 省略 chore:、refactor:、test: 以及僅文件相關的提交，除非使用者會注意到它們。

• 以下列方式結尾，確切格式如下：

  ## 安裝
  
  ```sh
  brew install juraj-blahunka/tap/simctlhouse   # 或：brew upgrade simctlhouse
  simctlhouse skill install                     # 僅一次，用於連結代理技能
  ```
  

將草稿寫入 dist/release-notes-X.Y.Z.md 並向使用者顯示全文。 請使用者接受或告知需要修改的內容；根據使用者的修改更新檔案並再次顯示全文。 重複此過程直到使用者明確接受，在此之前不要繼續進行建置。 該檔案將原文發布，因此不得包含任何針對使用者的內容，例如問題或待辦事項。

5. 建置發布版本

scripts/release.sh X.Y.Z

這需要幾分鐘時間，大部分時間在等待 Apple 的公證；最多允許 10 分鐘。 如果版本不匹配、原始碼未提交或標籤指向其他地方，它將拒絕執行；它會執行測試和 lint，透過 scripts/build.sh 建置，檢查 Apple 是否發布了公證憑證，並驗證自己的 tarball。 最後會列印 tarball 路徑、其 sha256 以及 dist/simctlhouse.rb。

6. 對 tarball 進行煙霧測試

對即將發布的確切位元組在真實模擬器上執行：

scripts/smoke-test.sh dist/simctlhouse-X.Y.Z-macos.tar.gz

它會將 tarball 解壓縮到臨時目錄，在其中連結技能，在暫用的 SIMCTLHOUSE_HOME 中取得一個裝置，檢查 daemon 是否啟動、能否停止和重新啟動，釋放裝置並等待 daemon 關閉它並自行退出，刪除它，並檢查之前存在的所有模擬器是否仍然存在。 首次啟動約需 30 秒；在負載較大的機器上最多允許 5 分鐘。 如果報告模擬器缺失，則向使用者顯示清單：其他代理可能同時刪除了它們自己的裝置，只有使用者才能判斷。

7. 發布前確認

從這裡開始的所有內容都是公開的且難以復原。 向使用者顯示版本、提交記錄 (git log --oneline -1)、sha256、煙霧測試結果、已接受的發布說明檔案以及以下步驟，並等待明確的同意。

8. 發布

按以下順序操作，以便每個已發布的步驟都指向已存在的內容：

git push origin main
git tag -a vX.Y.Z -m "simctlhouse X.Y.Z"
git push origin vX.Y.Z
gh release create vX.Y.Z dist/simctlhouse-X.Y.Z-macos.tar.gz \
    --repo juraj-blahunka/simctlhouse --verify-tag --title "simctlhouse X.Y.Z" --notes-file dist/release-notes-X.Y.Z.md

檢查上傳的 tarball 是否與公式描述的相同；不匹配表示 scripts/release.sh 在上傳後又執行了一次：

gh release download vX.Y.Z --repo juraj-blahunka/simctlhouse --pattern '*.tar.gz' --output - | shasum -a 256
grep sha256 dist/simctlhouse.rb

然後發布公式：

mkdir -p ../homebrew-tap/Formula
cp dist/simctlhouse.rb ../homebrew-tap/Formula/simctlhouse.rb
git -C ../homebrew-tap add Formula/simctlhouse.rb
git -C ../homebrew-tap commit -m "simctlhouse X.Y.Z"
git -C ../homebrew-tap push

9. 透過 Homebrew 驗證

推送會啟動 tap 的 tests 工作流程，該流程會稽核公式，在乾淨的 macOS 15 和 26 機器上安裝它，並執行其 test 區塊。 這是公式發布後使用者取得它之前的唯一一次真實安裝，因此請等待它通過：

commit="$(git -C ../homebrew-tap rev-parse HEAD)"
gh run list --repo juraj-blahunka/homebrew-tap --commit "$commit" --json databaseId,url   # 推送後幾秒鐘內為空
gh run watch <databaseId> --repo juraj-blahunka/homebrew-tap --exit-status

然後在此機器上檢查公式。 Homebrew 拒絕載入來自未受信任 tap 的公式，即使是 brew info 也如此，因此請先信任此公式；這會變更使用者的 Homebrew 配置，就像 brew install juraj-blahunka/tap/simctlhouse 一樣。 其餘操作僅讀取和下載；不會安裝任何內容：

brew tap juraj-blahunka/tap 2>/dev/null; brew update
brew trust --formula juraj-blahunka/tap/simctlhouse
brew info juraj-blahunka/tap/simctlhouse            # 顯示 X.Y.Z
brew fetch --force juraj-blahunka/tap/simctlhouse   # 下載並檢查 sha256
brew audit --strict --online juraj-blahunka/tap/simctlhouse

如果使用者已從 tap 安裝了 simctlhouse，則建議執行 brew upgrade simctlhouse，然後執行 simctlhouse --version 和 simctlhouse skill status。

10. 回報

向使用者提供發布 URL (gh release view vX.Y.Z --repo juraj-blahunka/simctlhouse --json url -q .url)、tap 提交記錄、其通過的 tests 執行的 URL，以及安裝命令 brew install juraj-blahunka/tap/simctlhouse。

從失敗的發布中復原

• 在第 8 步之前失敗：沒有任何內容是公開的。修正原因並重新開始；重新執行 scripts/release.sh 是安全的。
• 標籤已推送，但 Release 缺失：再次執行 gh release create 步驟。
• Release 已建立，但 tap 未更新：再次執行 tap 相關步驟。
• tap 的 tests 執行失敗：向使用者顯示失敗步驟的日誌 (gh run view <databaseId> --repo juraj-blahunka/homebrew-tap --log-failed)，因為現在安裝的使用者會遇到相同的失敗。 透過新的 tap 提交向前修復；切勿強制推送 tap，因為使用者的 brew update 會拉取它。
• 發布後需要修正說明：與使用者一起編輯 dist/release-notes-X.Y.Z.md，然後執行 gh release edit vX.Y.Z --repo juraj-blahunka/simctlhouse --notes-file dist/release-notes-X.Y.Z.md。
• 對於已上傳 tarball 的版本，切勿重新執行 scripts/release.sh，因為每次建置都會產生新的 sha256。 若要取代損壞的上傳，請先詢問使用者，然後使用 gh release upload vX.Y.Z <tarball> --clobber 上傳新建置的 tarball 並發布相符的公式。
• 未經使用者明確同意，切勿刪除或移動已推送的標籤或已發布的 Release。