juraj-blahunka/release

simctlhouseのリリース

このリポジトリのバージョンX.Y.Zを公開します。GitHubリリース（公証済みtarball）とタップ内のフォーミュラを含みます。 scripts/release.shがビルド、署名、公証、パッケージ化を行います。このスキルはその周辺処理すべてを担当します。 docs/how-to.md（「リリースの作成」）とdocs/decisions.mdのD27で設計を説明しています。

固定名:

項目	値
GitHubリポジトリ	juraj-blahunka/simctlhouse（リモート origin）
タップチェックアウト	../homebrew-tap、GitHub juraj-blahunka/homebrew-tap、juraj-blahunka/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:コミットでマイナーバージョンアップ、修正のみでパッチバージョンアップを提案します。

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        # タップが存在しクリーン
git -C ../homebrew-tap pull --ff-only            # タップが最新

originまたはタップが存在しない場合は停止し、ユーザーに何を作成すべきかを伝えます。GitHubリポジトリを自分で作成しないでください。 新しいタップには、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とスキルのユーザーが気づく内容を説明し、コードがどのように変更されたかではありません。

• リリースの概要を1～2文で始めます。

• 次にセクションを設け、空のセクションは省略します: ## New、## Changed、## Fixed、およびスクリプトやエージェントに影響を与える場合は最初に## Breaking（コマンドやフラグの変更、出力の変更、終了コードの変更）。

• 変更ごとに1つの箇条書きで、コマンドやフラグはバッククォートで囲みます（例: 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に書き込み、全文をユーザーに表示します。 ユーザーに承認するか、変更点を伝えるよう求めます。変更をファイルに適用し、再度全文を表示します。 ユーザーが明示的に承認するまで繰り返し、その前にビルドに進まないでください。 ファイルはそのまま公開されるため、質問やTODOなど、ユーザー宛ての内容を含んではいけません。

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でデバイスを取得し、デーモンが起動して停止・再起動できることを確認し、デバイスを解放してデーモンがシャットダウンして終了するのを待ち、デバイスを削除し、以前存在したすべてのシミュレーターがまだ存在することを確認します。 初回起動は約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で検証する

プッシュによりタップの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   # プッシュ後数秒間は空
github run watch <databaseId> --repo juraj-blahunka/homebrew-tap --exit-status

次にこのマシンからフォーミュラを確認します。 Homebrewは、誰も信頼していないタップからはフォーミュラを読み込もうとしません（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

ユーザーがすでにタップから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）、タップコミット、その合格したtests実行のURL、およびインストールコマンドbrew install juraj-blahunka/tap/simctlhouseを提供します。

失敗したリリースからの回復

• ステップ8より前の失敗: 何も公開されていません。原因を修正して最初からやり直します。scripts/release.shの再実行は問題ありません。
• タグはプッシュしたがリリースがない: gh release createの手順を再度実行します。
• リリースは作成したがタップが更新されていない: タップの手順を再度実行します。
• タップのtests実行が失敗: ユーザーに失敗したステップのログを表示します（gh run view <databaseId> --repo juraj-blahunka/homebrew-tap --log-failed）。今インストールするユーザーも同じ失敗に直面するためです。 新しいタップコミットで先に修正します。タップへのforce-pushは絶対に行わないでください。ユーザーの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を実行し、一致するフォーミュラを公開します。
• ユーザーの明示的な承認なしに、プッシュされたタグや公開されたリリースを削除または移動しないでください。