Git Workflow Best Practices for Teams - txt1.ai

マーカス・チェン、12年間の分散開発チームのリーダーを持つシリーズCのSaaSスタートアップのエンジニアリングマネージャー

3年前、私たちのエンジニアリングチームはマージコンフリクト、失ったコード、デプロイの災害に苦しんでいた。18か月で8人から45人のエンジニアに成長し、非公式の「メインにコミットするだけ」というアプローチは、コンフリクト解決に毎週約23時間のコストをかける責任となってしまった。壊滅的なポイントは、製品ローンチ中にジュニア開発者が私たちの決済チームの3日間の作業を上書きしてしまった時に訪れた。その事件は、私たちに18万ドルの遅延収益をもたらし、貴重な教訓を教えてくれた。Gitワークフローは単なる技術的な詳細ではなく、チームの速度と製品の信頼性の基盤である。

今日、私たちのチームは3年前の4.2倍の速さでコードを出荷し、コード統合の問題に関連する生産インシデントは89％減少している。この変革は、より賢い人材を雇ったり、高価なツールを購入したりしたからではなく、チームの成長に合わせた規律あるGitワークフローを導入したから実現した。私は、混乱から一貫性へと導いた具体的な実践、パターン、原則を共有する。

なぜほとんどのチームがGitワークフローを間違えるのか

私がチームに見られる根本的な間違いは、Gitを単なるバックアップシステムとして扱い、コラボレーションプロトコルとして考えないことだ。エンジニアリングチームにコンサルティングを行うとき、私はしばしば彼らのGitの使用が個々の開発者の便宜に重点を置いており、チームの調整には向いていないことに気づく。開発者は気が向いたときに「修正」をしたり「更新」をしたりするメッセージと共にコミットし、ブランチはクリアな所有権やマージ戦略なしに数週間も存在し続ける。

このアプローチはソロ開発者や非常に小さなチームには問題なく機能する。しかし、約5-7人のアクティブな貢献者が相互に関連するコードで作業していると、亀裂が見え始める。私は30以上の異なるエンジニアリングチームのGit履歴を分析しており、そのパターンは一貫している。明確なワークフローの合意がないチームは、適切なワークフローがあれば防げた統合問題に15-25％の開発時間を費やしている。

問題が複雑になるのは、Gitが非常に柔軟であるためだ。特定のパターンに強制するような意見を持ったフレームワークとは異なり、Gitは自分を吊るすのに十分なロープを提供してくれる。主に直接コミットすることも、決してマージされないブランチを作成することも、共有ブランチの履歴を再書きすることも、何十もの異なる長寿命のフィーチャーブランチを同時に維持することもできる。Gitはあなたを止めないが、チームの生産性は低下する。

別の重要な問題は、Gitワークフローとデプロイ戦略の disconnect だ。私はチームがGit Flowのような複雑なブランチ戦略を採用しているのを見たが、彼らのデプロイパイプラインが単一の真実のソースを期待していることを考慮していない。その結果、実際にコードがプロダクションに到達する方法と一致しない複雑なブランチ管理が生じる。あなたのGitワークフローは、理想的なブログ投稿からのプロセスではなく、デプロイの現実を反映する必要がある。

Gitで成功するチームには1つの共通の特徴がある。それは、彼らが自分たちのワークフローについて明示的な決定を下し、その決定を明確に文書化していることだ。彼らは単にGitを使用するだけではなく、特定のチームサイズ、デプロイ頻度、リスク耐性に対応するGit戦略を設計している。この意図性がすべての違いを生む。

チームサイズに合った正しいブランチ戦略の選び方

すべてのブランチ戦略が同じように作られているわけではなく、「最良」の戦略は完全にチームの文脈に依存する。私はさまざまなチームで4つの異なるブランチ戦略を実装しており、それぞれに適したポイントがある。戦略をチームサイズおよびデプロイの周期に合わせる方法について私が学んだことを説明しよう。

Gitワークフローは単なる技術的な詳細ではなく、チームの速度と製品の信頼性の基盤である。高パフォーマンスのチームと苦労しているチームの違いは、しばしば彼らがどれだけ意図的にブランチ戦略を設計しているかにかかっている。

1-5人の開発者が1日に何度もデプロイを行うチームには、トランクベースの開発がほぼ無敵である。このアプローチでは、全員が非常に短命のフィーチャーブランチを持つ単一のメインブランチで作業を続ける（数時間ではなく、数日間）。私の前のスタートアップでは、4人のチームがトランクベースの開発を行い、1日に8-12回デプロイしていた。私たちのフィーチャーブランチは平均3.2時間でマージされた。これにより、アイデアから本番環境へのコードが当日中に移動し、すべての変更が常に混ざり合っているため、統合の問題が即座に発見された。

トランクベースの開発を成功させるための鍵はフィーチャーフラグである。完成していない機能がデプロイを妨害するわけにはいかないので、フラグで未完成の作業を隠す。私たちは最初にシンプルな環境変数システムを使用し、成長に伴いLaunchDarklyに移行した。これにより、機能の可視性を独立して管理しながら、コードを継続的にマージすることができた。

6-20人の開発者が日次または週次のデプロイサイクルを持つチームには、GitHub Flowが構造とシンプルさのバランスを提供する。この戦略では、常にデプロイ可能な1つのメインブランチを維持し、新しい作業のためにフィーチャーブランチを作成し、レビュー後にプルリクエスト経由でマージする。私たちは10人のエンジニアを超えた成長に伴ってこれを採用した。私たちの平均フィーチャーブランチは現在2.1日存在し、毎朝午前10時にスタンドアップ後にデプロイしている。

GitHub Flowが機能するのは、誰もが理解できるほどシンプルでありながら、混乱を防ぐのに十分な構造を持っているからだ。プルリクエストは質のゲートとなり、すべての変更はマージ前にレビュー、テスト、議論される。私たちは、支払いまたは認証コードに触れるPRには2つの承認を必要とし、それ以外のすべてには1つの承認を必要とする。これは、そうでなければプロダクションに到達していた127の潜在的なバグを捕捉した。

より大きなチーム（20人以上）や複雑なリリーススケジュールを持つチームには、Git Flowが必要な構造を提供する。この戦略では、プロダクション用のメイン、統合用の開発、リリースおよびホットフィックスブランチの複数の長寿命のブランチを使用する。私は45人のチームでGit Flowを実装し、厳格なQAサイクルで毎月のリリースを出荷した。オーバーヘッドは実際にあり、より多くのブランチを管理し、より多くのマージを行うようになるが、調整されたリリースに必要な制御を与えてくれる。

重要な洞察は、ブランチ戦略がデプロイの現実と一致するべきだということだ。継続的にデプロイする場合、複雑なブランチは単なるオーバーヘッドである。広範なQAが必要な予定されたリリースがある場合、その構造が必要だ。洗練されているように聞こえるからと言って戦略を無理に採用するな。

実際に役立つコミットメッセージ基準

私は以前、コミットメッセージはあまり重要ではないと思っていた。しかし、Git履歴を確認しながら4時間を費やして生産の問題をデバッグしようとしたとき、「修正」、「更新」、「変更」といったメッセージしか見つからなかった。その経験は私をコミットメッセージの熱心な支持者に変えた。良いコミットメッセージはコードと永遠に共存するドキュメントであり、検索可能で文脈があり、デバッグ時に非常に貴重である。

従来のコミットは私が関わるすべてのチームでの基準となった。それはシンプルな形式であり、タイプ（feat、fix、docs、refactor、testなど）、オプションのスコープ、説明から成る。たとえば、「feat(auth): GoogleログインのOAuth2サポート追加」や「fix(payments): 再試行時の重複課金を防ぐ」。この構造により、コミット履歴はスキャン可能になり、チェンジログ生成とセマンティックバージョニングのための自動化ツールを使用できるようになる。

私たちは、コミットメッセージが受け入れられる前に検証するGitフックでこれを強制している。当初、開発者は追加の構造に対して文句を言っていたが、2週間以内にみんながその明快さを評価するようになった。6か月前に特定の変更がなぜ行われたのか理解する必要があったとき、「fix(payments)」を検索すれば、関連するコミットをすぐに見つけられた。これにより、コード考古学において毎週約6時間の節約につながった。

コミットボディは変更の「なぜ」を説明する場所である。diffは何が変わったかを示し、コミットメッセージはなぜそれが変わったのか、どんな問題を解決するのかを説明するべきだ。私は開発者にチケット番号を含め、関連議論へのリンクを追加するよう促す。