git-workflow

Git ワークフロー

すべての変更は、レビューしやすく、復元可能な履歴を保てる、新しく作成した目的の明確なブランチで行います。書き換えずにマージし、ローカルの作業を決して失わないようにし、各プルリクエストは意味のある件名を付けたスカッシュコミット 1 つとして取り込みます。Git に関する依頼で許可されるのは、その操作に必要なリポジトリと GitHub の状態に限られます。

これらのデフォルトに関するユーザーの明示的な指示は、進行中の作業において該当するデフォルトのみを置き換えます。変更されるまで、ターンをまたいでその指示を維持してください。新しいリポジトリや操作には、それぞれ固有のスコープが必要です。

作業の開始または再開

• ベースはリモートのデフォルトブランチから特定し、main をハードコードしないでください。
• 新しい作業の自動的な事前確認として、リモートのデフォルトブランチとの同期を行ってください。安全でクリーンな更新に許可を求めないでください。
• ローカルのデフォルトブランチから新しい作業を開始する場合は、フェッチや編集の前にステータスを確認してください。クリーンであれば、フェッチして、取得したリモートのデフォルトブランチの先端まで自動的にファストフォワードしてください。ローカルだけのコミット、分岐、またはファストフォワードできない更新がある場合は停止してください。
• ローカルのデフォルトブランチのワークツリーがダーティな場合は、フェッチ、更新、編集を行う前に停止し、ユーザーに状態を破棄するか、保持して最新のリモートのデフォルトブランチから目的の明確なブランチ／ワークツリーを作成するかを選んでもらってください。回答を得る前に、どちらかを選んだり、スタッシュ、コミット、破棄を行ったりしないでください。
• 新たに選択または再利用した、それ以外のブランチやワークツリーでは、最初の編集の前にワークツリーがクリーンであることを確認し、リモートのデフォルトブランチをフェッチしてください。ダーティなファイルがあれば報告して停止し、自動的にスタッシュ、コミット、破棄しないでください。
• 新しい目的の明確なローカルブランチとワークツリーはすべて、フェッチしたばかりのリモートのデフォルトブランチの先端と完全に一致する位置に自動的に作成してください。目的の明確なブランチでリモートのデフォルトブランチを追跡するように設定しないでください。そのブランチをプッシュするときに限り、アップストリームを設定してください。
• 既存の目的の明確なブランチまたはワークツリーに入る場合は、編集前にフェッチして、そのリモートベースをマージしてください。
• 新しい作業を開始する前に、デフォルトブランチの健全性ゲートを適用してください。

更新、コミット、プッシュ

• ブランチの更新にはリモートベースをマージしてください。リベースは決して行わないでください。リモートベースとは、オープンな PR が対象とするブランチがリモートのデフォルトブランチである場合、または create-pr の手順 1 で定義された名前付きベース（バックポート用のリリースブランチなど）である場合、そのブランチを指します。名前付きベースを対象とするブランチには、リモートのデフォルトブランチを決してマージしないでください。オープンな PR がない場合、リモートベースはリモートのデフォルトブランチです。
• ネイティブスタックのレイヤーは、スタックの参照を通じて更新します。オープンな PR がデフォルト以外の別のブランチを対象としている場合、リモートベースはありません。マージやプッシュの前に停止し、ベースを選ぶのではなく、そのベースを報告してください。その後、ユーザーがベースを指定するか、PR をリスタックできます。
• 許可された PR の更新中は、選択した変更と現在のベースによって意図された動作が定まる競合を解決してください。両方の側に必要な動作を維持し、プロジェクトのツールで生成ファイルを再生成して、結果を検証してください。解決に重大な未確定の選択が必要な場合は、一時停止してください。新しい作業の事前確認中に競合を見つけた場合は、実装前に報告してください。
• コミットを amend しないでください。修正ごとに新しいコミットを追加してください。
• 強制プッシュは決して行わないでください。通常のプッシュが履歴の分岐によって拒否された場合は停止してください。
• 関連ファイルのみをステージし、シークレットや無関係なローカル作業は除外してください。
• GitHub リポジトリへの各コミット、プッシュ、プルリクエストの書き込み前に、公開ガードを実行してください。
• 簡潔な Conventional Commit の件名を命令形で使用してください。各コミットタイトルには、変更した仕組みだけでなく、確認可能な影響を記述してください。
• ユーザーが明示的に求めない限り、フックは実行してください。

公開前ガード

インストール済みのこのスキルから scripts/publication_guard.py を、Python 3.11 以降で実際のインストール先のパスを使って実行します。たとえば、python3 /path/to/git-workflow/scripts/publication_guard.py のように実行します。GitHub にサインイン済みの gh が必要です。コンテンツを受け取るリポジトリが公開リポジトリの場合、非公開の GitHub 参照とローカルマシンのパスをコンテンツから書き換えます。

• 各コミットの前に、メッセージをファイルに書き込み、staged --message-file FILE を実行してから、git commit -F FILE でコミットします。
• 各プッシュの前に、gh stack push、gh stack submit、gh stack link を含め、outgoing --base BASE を実行します。BASE は REMOTE/DEFAULT、またはスタックのレイヤーの場合は、その直下のブランチです。ブランチのプッシュ先リモート以外にプッシュする場合は、--remote NAME を追加します。上記のコミット手順でステージされた内容をコミットしてから、プッシュします。
• 各プルリクエストのタイトルまたは本文を書き込む前に、タイトルと本文をファイルに書き込み、pr --repo OWNER/REPO --title-file FILE --body-file FILE を実行します。ここで OWNER/REPO は、プルリクエストを作成するリポジトリです。その後、それらのファイルからプルリクエストを作成または編集します。これは、gh pr create、gh pr edit、gh api .../pulls --input FILE（確認済みのファイルから JSON を作成）、および gh stack submit と gh stack link が作成するタイトルと本文（その後、gh pr edit で調整します）に適用されます。

実行結果に応じて対応します。

• is not public; nothing checked または nothing to rewrite とともに終了コード 0 が返された場合：続行します。
• rewrote ... の行とともに終了コード 0 が返された場合：ステージされたファイルと、渡したファイルには書き換え後のテキストが保存されています。また、それらのファイルへの未ステージの編集にも同じ書き換えが適用されます。続行し、各 rewrote 行と placeholder 行を報告します。
• warning: commit ... pushing publishes that commit unchanged の場合：履歴は書き換えられません。プッシュ時に、該当するコミット名とファイルをユーザーに報告します。
• warning: PATH was not checked の場合：ガードはそのファイルをテキストとして読み取れませんでした。公開前に、非公開のリポジトリ名とローカルパスが含まれていないか、自分で確認して報告します。
• .github/publication-guard.json または keep パターンに関する warning: の場合：報告します。ガードは読み取れなかった内容に対して、デフォルトの keep リストを使用しました。
• 終了コード 2 の場合：Git または GitHub から、ガードが必要とする情報を取得できなかったか、引数が正しくありません。何も変更されていません。エラーが示す原因を修正して再実行します。終了コード 0 で実行されるまでは、決して公開しないでください。
• それ以外の終了コードの場合：ガードの実行に失敗しました。作業を中止し、公開せず、出力内容を報告します。

デフォルトブランチの健全性

新しい作業を始める前にデフォルトブランチの健全性を確認し、マージの直前にも毎回再確認します。プロジェクトがデフォルトブランチへのコミットに対して要求する CI を確認します。たとえば、プッシュ時の CI などです。統合デプロイは対象ではありません。現在の先端コミットは、最新の完了済み実行で判断します。それより前のコミットに対する実行は、先端について何も示しません。

• 成功: その実行が成功した場合、またはプロジェクトがデフォルトブランチへのコミットに対する CI を要求していない場合です。作業の開始とマージが可能です。
• 保留中: 先端に成功または失敗した実行はまだなく、実行がキューに入っているか、進行中の場合です。保留中は成功ではありません。作業の開始またはマージの前に、delivery-wait で結果を待ちます。また、その実行に取って代わったり、キャンセルしたりする変更を決してマージしないでください。
• 結果なし: 先端の最新の実行がキャンセルまたは置き換えられ、その後の実行がない場合、または実行がない場合です。これも成功ではありません。プロジェクトで可能であれば、必要な CI を再実行するか、起動します。それ以外の場合は、その旨を報告します。
• 失敗: その実行が失敗した場合です。まず成功状態にする必要があり、修正作業のみ開始またはマージできます。失敗したジョブとその原因を特定し、修正の担当者を探します。オープン PR、イシュー、別のセッションなどが該当します。担当者がおらず、現在の依頼でマージが許可されている場合は、修正を独立した作業項目として /deliver を通じて提出し、先にマージします。それ以外の場合は、失敗したジョブとその原因、および必要な修正を報告します。独立したローカル調査は続行できますが、それ以外の開発作業やマージは開始できません。

このルールは、原則として厳格に適用されます。無関係なドキュメントのみの変更をマージできるようにする場合などに限り、担当者またはプロジェクトが明示的に緩和できます。

マージ

• マージの前に毎回、デフォルトブランチの健全性を再確認します。
• プルリクエストはスカッシュマージし、その後、ソースブランチを削除します。
• スカッシュマージでは、プルリクエストのタイトルがベースブランチ上のコミットの件名になります。ブランチ上の個々のコミット件名は引き継がれません。変更全体がもたらす観測可能な影響を示す、Conventional Commit 形式の件名をタイトルに付けます。変更に含まれるコミットで最も多いタイプではなく、正味の効果に基づいてタイプを選びます。プロジェクトがコミット履歴から変更履歴やバージョン更新を生成する場合、規約に従わないタイトルでも問題なくマージされますが、その後、生成物からひそかに除外されます。
• スカッシュマージ後、ローカルのベースを同期し、マージ済みのローカルブランチを削除します。

GitHub のネイティブスタック

ユーザーがスタックを選択した場合、作業に実際の依存関係チェーンがある場合、または規模が大きいと確認済みのイシューを、累積的で個別にレビューできる複数のレイヤーに意図的に分割する場合は、公式の gh stack ワークフローを使用します。無関係な作業をスタックにしないでください。各レイヤーには、明確な主張、範囲が限定された差分、独自の検証、および要件の明示的な一部が必要です。

スタックの作成、同期、プッシュ、提出、レビュー、またはマージの前に、references/github-stacks.mdを読んでください。このリファレンスは、上記の「マージのみ」および「強制プッシュ禁止」のデフォルトに対する唯一の例外です。リベースと --force-with-lease が許可されるのは、クリーンでネイティブスタックであることを確認したうえで、検証済みの gh stack コマンドを使って実行する場合に限られます。生の git rebase、git push --force、手動の git push --force-with-lease は引き続き禁止です。