merge-branch-mac

mac ブランチへのマージ

mac ブランチを担当します。開発はまず Windows（および Android）向けに進められ、その後、macOS と iOS への作業は mac ブランチを通じて行われます。取り込むブランチには Windows と場合によっては Android の変更が含まれます。このマージには 2 つの役割があります。変更を取り込むことと、キャッチアップリストの正確性を保つことです。つまり、Windows の各動作が Mac で機能するか、まだ対応していないことを示す項目がある状態にします。

ブランチ。 通常は mac です。プロジェクトで指定されている名前を使ってください（mac-catch と呼んでいる場合もあります）。ブランチが存在しない場合は、その旨を伝え、作成する前に確認を求めてください。マージの方向はほぼ常に <main> → mac です。長期運用ブランチでは、破損の影響を抑えられる mac 側で解決と検証を行うという、merge-branch の方向ルールが推奨する方法です。

merge-branch に従ってください。 — 調査、原則の確認、「プロダクト上の決定を決して行わない」というルール、意図に基づく競合解決、検証、コミットのルールをすべて実施してください。このスキルでは、mac 向けの確認作業を追加します。

まず読むもの

• プラットフォームのキャッチアップトラッカー。 CATCHUP.md（多くの場合 docs/macos/ 内）、プラットフォームのマトリックス、またはプロジェクトの原則で Apple 向け作業の記録先として定められている場所です。すでに対応が必要な項目、既知のプラットフォーム差異、番号付け、以前のマージの状況が記載されています。デスクトップとスマートフォンの差異用に別のトラッカーがある場合は、それは別の軸です。プラットフォームに関する項目はそちらに記録しないでください。
• プロジェクトの macOS ドキュメント（docs/macos/ など。mac ブランチにしか存在しない場合もあります）。リリース、署名、更新に関する手順書も含みます。
• merge-branch の調査と同様に、git log --oneline mac..<main> と git diff --stat mac...<main> を確認します。取り込むコミット数に注意してください。数百件のコミットをマージする場合は、コミットごとではなく領域ごとに確認作業を行う必要があります。

mac 翻訳パス

変更を取り込むたびに、これは Mac でどう動作するか？ と考えてください。特に、もともと Windows 向けの次の箇所を重点的に確認してください。

箇所	現在の Windows での実装	Mac に必要なもの
データ、設定、キャッシュ、ログの保存先	%APPDATA%、%LOCALAPPDATA%	~/Library/Application Support、Caches、Logs — XDG にフォールバックしないこと。プロジェクトに既存のオーバーライド変数があれば維持すること
プロセスと IPC	名前付きパイプ、CreateNamedPipeW、tasklist／taskkill	Unix ソケット、pkill、cfg の境界の背後にある同じプロトコル
自動起動とトレイ	レジストリの Run キー、通知領域アイコン	ログイン項目または launch agent、メニューバー項目 — トレイの操作を黙って失わせないこと
スクリプトと動詞	.bat、PowerShell	POSIX スクリプトを動詞ごとに対応させること。シェルに相当するものがない .bat 専用の動作は、課題として記録すること
ショートカット	生の Ctrl チェック	「コマンドキー」を意味する場合はプラットフォームのコマンドキー（Cmd）。Ctrl の生チェックは、Ctrl が本当に意図されたものでない限り指摘事項とすること
ウィンドウの外観	カスタムタイトルバー、.ico、コンポジターの前提	信号機ボタン、フルスクリーンの動作、.icns、Dock
ファイル	パスとファイル名の前提、ファイル監視、fsync のセマンティクス	大文字小文字を区別しないが、その表記は保持するパス、FSEvents の動作、予約名なし
OS バージョンと環境	cmd /C ver、コンソールへの接続	sw_vers、接続先なし — Windows のパスは cfg(windows) に残すこと
リリースと更新	インストーラー、Authenticode、ファイルのインプレース置換	.dmg 内の .app、codesign と公証、同じロールバック機能を備えたバンドル全体の置換
依存関係	共通の [dependencies] にある Windows 専用クレート	[target.'cfg(target_os = "macos")'.dependencies] のエントリー、または境界
テスト	手作業で記述されたキー操作、パス、区切り文字	プラットフォーム固有の表記、またはそれを管理するヘルパー

各変更の判定は次の 3 つのいずれかで、レポートに明記します。

• そのまま対応します。
• mac の境界が必要です — cfg、ポートトレイト、プラットフォームアダプターなど。今回のマージで対応するか、内容と場所を示すトラッカーの行を追加します。
• 意図的に先送りします — 理由と、対応を再開するきっかけを記したトラッカーの行を追加します。

Mac で何も起きないことを黙って許容してはいけません。

• 仕組みは下位レイヤーに移してください。 共有コードのうち、本来プラットフォームの境界を設けるべき箇所に Windows 固有の仕組みがハードコードされている場合は、ソースブランチで対応すべき指摘事項です。漏れを残したままにする mac 側のパッチで対処してはいけません。
• Android 向けの変更は、通常 macOS ではなく iOS に対応します。このマージに無理に含めず、iOS 側の追従対応に向けて記録してください。
• 両方のブランチに番号付きの行がある場合、トラッカーの番号が衝突します。mac 側で番号を振り直し、マージコミットにその旨を記載してください。
• ソースブランチですでに Windows 側の実装と並べて mac 側の実装を追加している場合があります。 コンパイルしてテストしてください。Mac で一度もビルドされていない実装を初めて実行するのは、マージの機会です。

記録する

マージ後ではなく、マージの一環としてトラッカーを更新してください。マージで取り込んだ Windows の動作ごとに、何がそのまま対応できたのか、どの mac 対応が必要でその実装がどこにあるのか、何を先送りしたのかを記録します。先送りする各行には、初めて担当する人でも作業を始められるだけの情報を含めてください。Mac で欠けている Windows の動作について、記録する行を残さないマージは完了ではありません。

マージコミットメッセージにも、同じ概要を簡潔に記載します。何を取り込み、mac 側でどのような対応が必要だったのか、トラッカーのどの行を追加または完了したのかを記し、merge-branch がすでに記録を求めている判断事項も含めてください。

検証

• ホストのターゲットだけでなく、macOS 向けターゲットでもビルドとテストを行ってください。Windows マシンでは、cargo check --target aarch64-apple-darwin（ターゲットがインストールされている場合）で純粋な Rust クレートの型チェックはできますが、アプリのリンクや実行はできません。プロジェクトに macOS CI ジョブがある場合は、それがビルドとテストの判定基準になります。
• レポートでは、ターゲットごとの状態を文字どおりに記載してください。型チェック済み、ビルド済み、実行済み（Mac 上で実行した場合のみ）とし、このマシンから検証できなかったことも記載してください。成功したと受け取られるような表現は避けてください。
• 求められない限り、プッシュしないでください。