git-workflow

Git ワークフロー

効果的なバージョン管理とは、変更を追跡するだけではありません。チームが予測可能な形で協力し、自信を持ってリリースし、一貫した経緯を伝える履歴を維持できるようにすることです。適切なワークフローは、チームの規模、リリースの頻度、プロジェクトの速度を落とさずにどれだけのプロセスを取り入れられるかによって異なります。

ブランチ戦略の選択

すべてのチームに適したブランチモデルはありません。最適な選択は、リリースの頻度、チームの規模、許容できる手続きの煩雑さによって異なります。

戦略の比較

戦略	リリース頻度	チーム規模	複雑さ	最適な用途
トランクベース	継続的（1日に複数回）	任意（強力な CI があると最適）	低	SaaS、クラウドネイティブ、成熟した CI/CD を備えたチーム
GitHub Flow	必要に応じて（PR のマージごと）	小規模から中規模	低	Web アプリ、スタートアップ、シンプルさを求めるチーム
Git Flow	定期的／バージョン管理されたリリース	中規模から大規模	高	パッケージソフトウェア、モバイルアプリ、複数バージョンのサポート
GitLab Flow	環境への昇格	中規模から大規模	中	環境固有のブランチ（staging、production）が必要なチーム

選択ガイド

1. 継続的にデプロイしていますか？ - トランクベース開発を使用します。短期間で破棄するブランチ（数日ではなく数時間）、未完了の作業に対するフィーチャーフラグ、強力な CI が前提となります。
2. マージ時にデプロイしつつ、レビューの承認プロセスを設けたいですか？ - GitHub Flow を使用します。長期間維持するブランチ（main）を1つ用意し、フィーチャーブランチとプルリクエストをマージの承認プロセスとして使用します。
3. スケジュールに沿ってバージョン付きリリースを出荷していますか？ - Git Flow を使用します。develop と main のブランチを分け、安定化用のリリースブランチと緊急パッチ用のホットフィックスブランチを用意します。
4. 環境間で昇格させていますか？ - GitLab Flow を使用します。環境ブランチ（staging、production）を main の下流に置き、マージを一方向に進めます。

各戦略の詳細な仕組み、フィーチャーフラグの統合、戦略間の移行方法については、ブランチ戦略リファレンスを参照してください。

---

コミットメッセージの規約

適切なコミットメッセージは、3つの対象に役立ちます。PR を読むレビュアー、翌月に git log を読む開発者、そして変更履歴やバージョン更新を生成する自動化ツールです。

Conventional Commits の形式

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

よく使われるコミットタイプ

タイプ	目的	バージョンへの影響
feat	ユーザーに見える新機能	マイナーバージョンを更新
fix	バグ修正	パッチバージョンを更新
refactor	動作を変更しないコードの再構成	なし
perf	パフォーマンスの改善	パッチバージョンを更新
test	テストの追加または更新	なし
docs	ドキュメントのみ	なし
chore	ツール、依存関係、ビルド設定	なし
ci	CI/CD パイプラインの変更	なし
build	ビルドシステムまたは依存関係の変更	なし

破壊的変更

互換性のない変更を示すには、タイプの後に ! を付けるか、フッターに BREAKING CHANGE: を追加します。どちらの表記も、自動リリースツールと併用するとメジャーバージョンの更新を引き起こします。

feat(api)!: remove deprecated /v1/users endpoint

BREAKING CHANGE: The /v1/users endpoint has been removed. Use /v2/users instead.

セマンティックバージョニングとの対応

コミットに含まれる内容	バージョン更新	例
fix:	パッチ（1.0.0 -> 1.0.1）	バグ修正
feat:	マイナー（1.0.0 -> 1.1.0）	新しい機能
BREAKING CHANGE または !	メジャー（1.0.0 -> 2.0.0）	互換性のない変更

スコープの命名パターン、複数行の本文ガイドライン、変更履歴の自動生成設定、Git フックによる検証については、コミット規約リファレンスを参照してください。

---

プルリクエストのワークフロー

ほとんどの Git ワークフローでは、プルリクエストが主要な共同作業の場となります。その品質は、レビューの速度、欠陥の発見、チームの開発速度に直接影響します。

PR サイズのガイドライン

PR サイズ（変更行数）	レビューの品質	推奨事項
< 50	優秀 — レビュアーがほとんどの問題を見つけられます	スタック型 PR に最適です
50-200	良好 — 認知負荷を管理しやすい規模です	ほとんどの変更に適した規模です
200-400	許容範囲 — 集中的なレビュー時間が必要です	単独レビューの上限です
400+	不良 — レビュアーが疲弊し、欠陥が見逃されます	小さな PR に分割します

PR の基本プラクティス

• PR ごとに懸念事項を 1 つにする - PR では機能の追加、バグの修正、モジュールのリファクタリングなど、1 つのことだけを行います。懸念事項を混在させると、レビューが難しくなり、差し戻しのリスクも高まります。
• 明確な説明を書く - 何を変更したか、なぜ変更したか、どう検証するかを記載します。関連するチケットやイシューへのリンクを含めます。
• レビュー可能な差分を保つ - 大規模な機械的変更（名前変更、フォーマットなど）は、ロジックの変更とは別の PR にします。
• フィードバックに速やかに対応する - 放置された PR はマージコンフリクトが蓄積し、依存する作業を妨げます。

マージ戦略

戦略	履歴の形状	最適な用途
マージコミット	ブランチのトポロジーを保ち、マージノードを作成します	オープンソースプロジェクト、監査証跡
スカッシュマージ	ブランチを main 上の単一コミットにまとめます	中間コミットが整理されていない機能ブランチ
リベースマージ	マージコミットのない直線的な履歴です	整然とした直線的なログを求めるチーム

説明用テンプレート、CODEOWNERS の設定、ブランチ保護ルール、スタック型 PR のワークフロー、レビュー担当者の割り当て戦略については、PR パターンのリファレンスを参照してください。

---

リリース管理

リリース管理は、開発とデプロイの橋渡しをします。リリースが継続的、定期的、またはバージョン管理されているかによって、アプローチが異なります。

リリースモデル

モデル	仕組み	使用する場面
継続的リリース	マージされた PR をすべて自動でデプロイします	強固な CI/CD と監視体制を備えた SaaS
定期リリース	変更を蓄積し、一定の間隔（毎週、隔週など）でリリースします	調整期間が必要なチーム
バージョン管理されたリリース	明示的なバージョンタグと、安定化のためのリリースブランチを使用します	ライブラリ、API、パッケージソフトウェア

リリース用 Git タグ

タグは、特定のコミットをリリースポイントとして示します。作成者、日付、メッセージのメタデータを保存できるため、リリースには注釈付きタグを使用してください。

# Create an annotated release tag
git tag -a v1.2.0 -m "Release 1.2.0: Add user dashboard and fix auth timeout"

# Push tags to remote
git push origin v1.2.0

# List existing tags matching a pattern
git tag -l "v1.*"

自動リリースパイプライン

Conventional Commits とリリース自動化ツールを組み合わせると、パイプラインで次のことができます。

1. 前回のタグ以降のコミットを分析し、次のバージョンを決定する
2. コミットメッセージから変更履歴を生成または更新する
3. git タグを作成する
4. アーティファクトをビルドして公開する
5. ホスティングプラットフォーム（GitHub/GitLab）にリリースエントリーを作成する

これにより、手動でのバージョン決定が不要になり、変更履歴を実際の変更と確実に同期できます。

ホットフィックスのワークフロー

本番環境で重大なバグが見つかった場合：

1. 開発ブランチではなく、リリースタグからブランチを作成する
2. 最小限の修正を適用する
3. 新しいパッチリリースにタグを付ける
4. 再発を防ぐため、修正をメインの開発ラインに前方マージする

# Branch from the release tag
git checkout -b hotfix/fix-auth-crash v1.2.0

# After fixing and committing
git tag -a v1.2.1 -m "Hotfix: prevent auth crash on expired tokens"
git push origin v1.2.1

# Merge fix back to main
git checkout main
git merge hotfix/fix-auth-crash

---

クイックリファレンス：よくあるワークフローの問題

問題	考えられる原因	解決策
マージコンフリクトが頻発する	ブランチが長期間存続している、統合の頻度が低い	毎日 main を機能ブランチにマージするか、トランクベース開発に切り替える
main ブランチが壊れている	PR で CI を実行していない、テストカバレッジが不十分	マージ前に CI の成功を必須にし、ブランチ保護を追加する
リリース内容が不明確	コミット規約がない、変更履歴を手動で作成している	Conventional Commits を採用し、変更履歴の生成を自動化する
PR レビューに時間がかかる	PR が大きすぎる、担当が明確でない	サイズのガイドラインを設定し、CODEOWNERS を構成して、スタック型 PR を使用する
main に誤ってコミットしてしまう	ブランチ保護がない	ブランチ保護ルールを有効にし、PR レビューを必須にする

---

参考ファイル

参考資料	内容
ブランチ戦略	トランクベース開発、GitHub Flow、Git Flow、GitLab Flow — 仕組み、フィーチャーフラグ、比較表
コミット規約	Conventional Commits の形式、スコープのパターン、セマンティックバージョニング、変更履歴の自動生成、Git フック
PR のパターン	サイズのガイドライン、説明のテンプレート、CODEOWNERS、マージ戦略、ブランチ保護、スタック型 PR

---

他のスキルとの連携

状況	推奨スキル
ブランチ保護用の CI/CD パイプラインを設定する	テスト戦略のために krzysztofsurdy/code-virtuoso から knowledge-virtuoso をインストールします
Git のリリースタグと連動する API バージョニング	API 設計の原則のために krzysztofsurdy/code-virtuoso から knowledge-virtuoso をインストールします
マイクロサービス間のリリースを調整する	マイクロサービスのパターンのために krzysztofsurdy/code-virtuoso から knowledge-virtuoso をインストールします
スプリントに合わせたリリース計画	スクラムのワークフローのために krzysztofsurdy/code-virtuoso から knowledge-virtuoso をインストールします