💡

実務でGitHubの運用ルールを策定した話

に公開
GitHub
ブランチ戦略
git運用
運用ルール
tech

はじめに

こんにちは！今回は、最近取り組んでいる「Githubの運用ルールを策定」について、その過程で得た経験や知見を共有したいと思います。チームが拡大や外部エンジニアとの協力の中で直面した課題をどのように解決したかを共有したいと思います。

抱えている課題

チームメンバーが増えるにつれ、他のメンバーの作業内容の把握が難しくなり、以下のような問題が発生していました。

  • コミットメッセージやPRの記述が不十分なため、どのような変更が行われたのかを把握するのに時間がかかり、メンテナンスや機能開発の効率が低下していました。

  • PRに必要な情報が不足していたり、変更点の量が多すぎるため、レビューに時間がかかり、ボトルネックとなることが多くなっていました。

  • ブランチ名や運用が統一されておらず、どのブランチが何を目的としているのかが分かりにくく、リリースの際に混乱を招いていました。

これらの課題に対処するため、Githubの運用ルールを策定することにしました。

GitHubの運用ルール

まず、私はコミット、PR、ブランチに関するコンベンションを定めることを考えました。ベストプラクティスを調査し、現状の組織や業務状況に適した現実的なコンベンションを策定しました。そして、それをもとにガイドブックを作成し、チームメンバーに共有しました。その後、チームメンバーからフィードバックを受けながら、コンベンションを一緒に調整し、チーム全体で作り上げていきました。

Branch戦略

GitHub Flow戦略
0から作る新たなプロジェクトだったので、特に開発ブランチやSTGブランチは不要だと思い、シンプルで管理しやすい運用にしたいと思い、GitHub Flowの戦略を取り入れることにしました。

  • ブランチの種類
  1. メインブランチ (main)
    • 常にリリース可能な最新バージョンを保持します。
    • 直接コミットせず、Pull Request (PR)を通じてのみマージします。
  2. 機能ブランチ (feature/*)
    • 新しい機能を開発するためのブランチです。
    • mainブランチから派生させます。
    • 命名規則：feature/{機能名} (例：feature/get-user-api)
    • 開発が完了したら、PRを作成し、mainブランチにマージします。
  3. バグ修正ブランチ (hotfix/*)
    • 機能開発PRのマージ後にバグがあった場合、修正を行うためのブランチです。
    • mainブランチから派生させます。
    • 命名規則：hotfix/{バグ修正名} (例：hotfix/login-error)
    • 修正が完了したら、PRを作成し、mainブランチにマージします。
  • リリースまでのフロー
  1. mainブランチからfeature/name や hotfix/name のブランチを切る
  2. そのブランチで開発
  3. PR作成
  4. PRレビュー
  5. PR承認
  6. mainブランチへマージ

Pull Request Convention

  • レビュー可能な単位：1つのPRがあまりに大きくなるとレビューが難しくなるため、適度なサイズにする
    • ファイル数：明確な基準はないが、10〜20ファイル以内に抑えることを推奨
  • 1つのテーマ：PRは1つのテーマに絞る。例えば、バグ修正と新機能追加を1つのPRに含めない
  • 頻繁なマージ：変更が小さく頻繁にマージされるようにすることで、大きなコンフリクトを避けやすくなります
  • 必ずレビューを受けてからマージすること（少なくとも1人の承認者）
  • 承認後にPRに変更が加えられた場合、再度承認を受けること（Github branch protection設定）
  • PRのタイトルと説明には変更内容と目的を明確に記載する（説明はテンプレート有）

Pull Request テンプレート

Commit Convention

  • 1コミット = 1つの変更：後から変更の追跡や元に戻す作業が容易になります

  • 意味のあるメッセージ：何を、なぜ行ったかを明確に記述する

  • 小さなコミット：大きな変更は小さなコミットに分ける

  • 一貫性を保つために、以下のフォーマットを使用する（テンプレート有）

    [タイプ] 概要
詳細な説明（option）

    • 基本日本語で作成

    • タイプをPrefixでつける

      • feat: 新しい機能
      • fix: バグの修正
      • docs: ドキュメントのみの変更
      • style: 空白、フォーマット、セミコロン追加など
      • refactor: 仕様に影響がないコード改善(リファクタ)
      • perf: パフォーマンス向上関連
      • test: テスト関連
      • chore: ビルド、補助ツール、ライブラリ関連

    • 例

      [feature] 〇〇の追加

[fix] 〇〇なため、△△を修正
レスポンスデータの内部構造が期待値と異なったため、仕様通り修正

    • テンプレートの設定

      git config --local commit.template .github/.gitmessage.txt

    • 確認

      • VScode

    - Terminal
        
        ```bash
        [feat/fix/docs/style/refactor/perf/test/chore] 概要(〇〇なため、△△を追加)
        詳細な説明（option）
        
        # Please enter the commit message for your changes. Lines starting
        # with '#' will be ignored, and an empty message aborts the commit.
        #
        # On branch main
        # Your branch is up to date with 'origin/main'.
        #
        # Changes to be committed:
        #       new file:   .gitmessage.txt
        #
        ```

どう改善したか？

ルールを守るのは当初大変でしたが、運用を明確にし、みんなでそのルールを守ることで、以下のような改善が見られました。

効率的なコードレビュー：　PRに必要な情報が揃っているため、レビューがスムーズに行われ、レビューの質とスピードが向上しました
容易な履歴追跡：　過去は変更内容とコミットメッセージがズレたり、PRに何も書いてなくてバグ調査の際に難航でしたが、みんなが一貫したコミットメッセージやPRを書くことで、過去の変更履歴を簡単に追跡できるようになり、バグ修正や機能追加の際に非常に役立ちました
作業の効率アップ：　コミットメッセージやPRに何を書けばいいかと迷わず、すぐにかけるようになりました
効率的なコミュニケーション：　コミットメッセージやPRテンプレートを通じて、何が変更されたかを明確になったのとブランチルールを決めることで不要なコミュニケーションが大分なくなりました

Discussion