diff --git a/README.md b/README.md index d848e13c..be0d90c6 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,7 @@ footer: ©2015 - 2024 Future Enterprise Coding Standards - Future Corporation | 2 | [SQL コーディング規約](./documents/forSQL/) | | | 3 | [AWS インフラリソース命名規約](./documents/forAWSResource/) | | | 4 | [OpenAPI Specification 規約](./documents/forOpenAPISpecification/) | | +| 5 | [Gitブランチフロー規約](./documents/forGitBranch/) | | --- diff --git a/documents/forGitBranch/git_branch_standards.md b/documents/forGitBranch/git_branch_standards.md index fae4609b..37dd6ca0 100644 --- a/documents/forGitBranch/git_branch_standards.md +++ b/documents/forGitBranch/git_branch_standards.md @@ -27,8 +27,8 @@ meta: 一般的なGitブランチ運用のプラクティスに従い、本規約も以下の方針に則る。 -- すべての機能開発や不具合修正に、機能ブランチを使用する -- プルリクエストを経由して機能ブランチの修正内容をマージする +- すべての機能開発や不具合修正に、featureブランチを使用する +- プルリクエストを経由してfeatureブランチの修正内容をマージする - 永続ブランチは各環境にデプロイ可能となるよう整合性を保つ # ブランチの種類 @@ -42,7 +42,7 @@ meta: | `develop` | 開発の大元 | 永続的 | `main` | `develop` 固定。複数必要な場合は `develop2` と連番にする | ❌️ | | `release` | リリース作業用途 | 短命 | `develop` | `release/${yyyymmdd}` や `release/${リリースバージョン}` など | ❌️ | | `hotfix` | mainブランチに対する即時修正 | 短命 | `main` | `hotfix/${チケット番号}`: featureブランチに準じる | ✅️ | -| `topic` | 複数人での機能開発用と | 短命 | `feature` | `topic/${チケット番号}`: featureブランチに準じる | ✅️ | +| `topic` | 複数人での機能開発用途 | 短命 | `feature` | `topic/${チケット番号}`: featureブランチに準じる | ✅️ | ※1: topicブランチを利用する場合は、派生させたfeatureブランチへの直プッシュはNGとなる @@ -126,13 +126,12 @@ featureブランチで実現する機能を複数人で開発する場合に使 - [GitHub flow](https://docs.github.com/ja/get-started/using-github/github-flow) - [GitLab Flow](https://docs.gitlab.co.jp/ee/topics/gitlab_flow.html) -現実的に利用する可能性が高いGitHub Flow、GitLab Flowとその亜種を、運用コストが低い順に３つ示す。本規約ではこれらからベースとなるパターンを選択する。 +システム開発において、現実的に利用する可能性が高いのは次の2パターンである。本規約ではこれをベースとなるパターンとして選択することとする。 -| 名称 | 利用ブランチ | デフォルトブランチ | リリース作業ブランチ | 使い所 | 備考 | -|------------------|-------------------------------------------------------------------------|-----------|-----------|--------------------------------------------------------|----| -| GitHub Flow | `main`
`feature` | `main` | `main` | ・開発人数がごく限られる場合 | | -| Lite GitLab Flow | `main`
`develop`
`feature`
`topic`
`hotfix` | `develop` | `develop` | ・稼働済みのプロダクトなど、品質を保証する必要がある場合 | ※1 | -| GitLab Flow | `main`
`develop`
`release`
`feature`
`topic`
`hotfix` | `develop` | `release` | ・リリース作業と開発作業が並行して行う必要がる場合
・断面を指定して複数テスト環境にデプロイしたい場合 | ※2 | +| 名称 | 利用ブランチ | デフォルトブランチ | リリース作業ブランチ | 使い所 | +|------------------|-------------------------------------------------------------------------|-----------|-----------|--------------------------------------------------------| +| Lite GitLab Flow
※1 | `main`
`develop`
`feature`
`topic`
`hotfix` | `develop` | `develop` | ・GitLab Flowからreleaseブランチを除いたパターン
・リリース作業時にdevelopマージを止められる場合 | +| GitLab Flow | `main`
`develop`
`release`
`feature`
`topic`
`hotfix`
※2 | `develop` | `release` | ・リリース作業と開発作業が並行して行う必要がある場合
・断面を指定して複数テスト環境にデプロイしたい場合 | - ※1: 特定の呼称はないためLite GitLab FLowと命名する - ※2: 本規約では、本来のGitLab Flowの呼称である `production`を`main`、`pre production`を`release`に言い換えている @@ -143,8 +142,7 @@ featureブランチで実現する機能を複数人で開発する場合に使 | 名称 | 開発環境 | ステージング環境 | プロダクション環境 | 備考 | |------------------|---------|----------|-----------|----------------------------------------------------------------------------------------------------------------------------------------| -| GitHub Flow | feature | main | main | ・ステージング環境が存在しないことも多い | -| Lite GitLab Flow | feature | develop | main | ・開発環境へはfeatureブランチのPRレビュー後にデプロイする
・開発環境へのデプロイ漏れを防ぐため定期的にCI/CDでdevelop断面をリリースすることを推奨する
・ステージング環境へはdevelopマージをトリガーにCI/CDでデプロイを推奨する | +| Lite GitLab Flow | develop | develop | main | ・開発環境へはdevelopマージをトリガーにCI/CDでデプロイを推奨する
・開発環境へのデプロイ漏れを防ぐため定期的にCI/CDでdevelop断面をリリースすることを推奨する
・動作確認など理由がある場合はfeatureブランチから直接開発環境へのデプロイも許容する
・ステージング環境は日次など定期的なCI/CDによるデプロイを推奨する | | GitLab Flow | develop | release | main | ・開発環境へはdevelopマージをトリガーにCI/CDでデプロイを推奨する
・検証期間が長引きそうな場合は、PRレビュー承認後にfeatureブランチから開発環境へのデプロイを許容する | # ブランチ戦略の拡張 @@ -158,7 +156,7 @@ featureブランチで実現する機能を複数人で開発する場合に使 ![multi develop branch](img/branch_strategy_multi_develop.drawio.png) -日々のエンハンス開発と並行して、数カ月後に大型リリースを行いたい場合がある。このときは複数リリースバージョンを並行して開発するため、 `develop`、`develop2` といった複数の開発ブランチを作る必要がある。 +日々のエンハンス開発と並行して、数カ月後に大型リリースを行いたい場合がある。このときは複数リリースバージョンを並行して開発するため、 `develop`、`develop2` といった複数のdevelopブランチを作る必要がある。 概要: @@ -203,8 +201,8 @@ featureブランチで実現する機能を複数人で開発する場合に使 具体的には次の3ケースそれぞれで、「マージコミット」「リベース」「スカッシュマージ」のどれを採用するか判断する。 -1. 開発ブランチから機能ブランチへ変更を取り込む -2. 機能ブランチから開発ブランチへ変更を取り込む +1. developブランチからfeatureブランチへ変更を取り込む +2. featureブランチからdevelopブランチへ変更を取り込む 3. 永続ブランチ間で変更を取り込む 以下に影響を与えるため、Gitの利用開始前に決めチームで統制を図ることが重要である。 @@ -213,11 +211,11 @@ featureブランチで実現する機能を複数人で開発する場合に使 - 開発プロセスの円滑な進行 - 最終的なソフトウェア品質 -## 1. 開発ブランチから機能ブランチへ変更を取り込む +## 1. developブランチからfeatureブランチへ変更を取り込む -機能ブランチでの作業中に、開発ブランチが更新された場合、品質保証の観点で開発ブランチの変更を機能ブランチに取り込んだ上で、テストなどの検証作業を行う必要がある。 +featureブランチでの作業中に、developブランチが更新された場合、品質保証の観点でdevelopブランチの変更をfeatureブランチに取り込んだ上で、テストなどの検証作業を行う必要がある。 -[開発ブランチの変更を機能ブランチに取り込む方法](merge_develop_to_feature.md)に記載した2つの方法のうち、「リベース」による方法を推奨する。 +[developブランチの変更をfeatureブランチに取り込む方法](merge_develop_to_feature.md)に記載した2つの方法のうち、「リベース」による方法を推奨する。 ![リベース](img/merge_strategy_develop_to_feature_rebase.drawio.png) @@ -230,11 +228,11 @@ featureブランチで実現する機能を複数人で開発する場合に使 この選択にあたり、以下の設定を行う。 1. `git pull` 時の挙動がリベースになるよう `git config pull.rebase true` を実行する -2. 開発ブランチの変更を取り込む場合、同じコンフリクトの解消を何度も求められることを解消するため、`git config rerere.enabled true` を実行する +2. developブランチの変更を取り込む場合、同じコンフリクトの解消を何度も求められることを解消するため、`git config rerere.enabled true` を実行する マージによる変更の取り込みが既存のブランチを変更しないのに対し、リベースは全く新しい（元のコミットIDとは別のコミットIDで）コミットを作成するため、次の1点に注意すること。 -1. リモートにプッシュ済のブランチがあり、開発ブランチからさらに変更をリベースで取り込んだ場合、強制プッシュ（Force Push）が必要になる +1. リモートにプッシュ済のブランチがあり、developブランチからさらに変更をリベースで取り込んだ場合、強制プッシュ（Force Push）が必要になる - `git push origin HEAD --force-with-lease --force-if-includes` とすることで、意図せずリモートブランチの変更を上書きしないようにする - `--force-with-lease`: ローカルのリモート追跡ブランチの ref とリモートの ref を比較し、ローカルの状態が最新でない場合（プッシュ先のリモートブランチに変更が入ったが、ローカルで `git fetch` していない場合）は、プッシュに失敗する。逆にいうと、プッシュ前に `git fetch` を実行済みの場合は、リモートの変更を上書きする形で強制プッシュができてしまうため、これを防ぐには `--force-if-includes` フラグを併用する - `--force-if-includes`: リモート追跡ブランチの変更がローカルに全て取り込まれていない場合は、プッシュに失敗する。これにより意図せず他の人のコミットを上書きすることを防ぎつつ、必要な変更を強制的にプッシュすることができる @@ -254,23 +252,23 @@ featureブランチで実現する機能を複数人で開発する場合に使 ::: -## 2. 機能ブランチから開発ブランチへ変更を取り込む +## 2. featireブランチからdevelopブランチへ変更を取り込む -プルリクエスト（以下、PR）を経由して、開発が完了した機能ブランチをメインの開発ブランチに取り込むためには、GitHub（GitLab）上でPRを経由する運用を行うこと。 +プルリクエスト（以下、PR）を経由して、開発が完了したfeatureブランチをメインのdevelopブランチに取り込むためには、GitHub（GitLab）上でPRを経由する運用を行うこと。 -[開発ブランチに機能ブランチの変更を取り込む方法](merge_feature_to_develop.md)に記載した3パターンのうち、「スカッシュマージ」による方法を推奨する。 +[developブランチにfeatureブランチの変更を取り込む方法](merge_feature_to_develop.md)に記載した3パターンのうち、「スカッシュマージ」による方法を推奨する。 ![Squash and Merge](img/merge_strategy_feature_to_develop_squash_and_merge.drawio.png) 理由は次の通り。 -- 機能ブランチのコミットログが、汚れることは許容したいため -- 開発ブランチの履歴をクリーンに保てるため +- featureブランチのコミットログが、汚れることは許容したいため +- developブランチの履歴をクリーンに保てるため - PRをよりシンプルに保つインセンティブとしたいため（単一のコミットメッセージで表現できる程度の方がレビューコストも小さいため） -「スカッシュマージ」を行うと、変更元の機能ブランチのコミットをまとめたコミットが新たに作成されるめ、元の機能ブランチを再利用しPRを作成するとコンフリクトが発生する。そのためマージ後はリモート/ローカルの双方で速やかに機能ブランチを削除させるため、以下の設定を加える。 +「スカッシュマージ」を行うと、変更元のfeatureブランチのコミットをまとめたコミットが新たに作成されるめ、元のfeatureブランチを再利用しPRを作成するとコンフリクトが発生する。そのためマージ後はリモート/ローカルの双方で速やかにfeatureブランチを削除させるため、以下の設定を加える。 -- マージ後に機能ブランチを自動削除する設定 +- マージ後にfeatureブランチを自動削除する設定 - リモート側: GitHubでは「Automatically delete head branches」を選択することで、マージ後に自動でブランチの削除が行われる（GitLabではプロジェクト設定で「Enable "Delete source branch" option by default」を選択する） - ローカル側: `git config --global fetch.prune true`: リモート側で削除されたブランチをローカル側でも削除する @@ -279,7 +277,7 @@ featureブランチで実現する機能を複数人で開発する場合に使 1. 部分的なコミットの取り消しができない - 履歴上は1つのコミットになるため、マージ後に一部の変更だけの取り消しが不可能。そのためPRをなるべく小さなまとまりにする 2. Authorが失われる - - 機能ブランチにコミットを行った人がAuthorになるのではなく、「スカッシュマージ」を行った人がAuthorになる。OSS開発を行う場合など、厳密にコントリビューションを管理する必要がある場合は注意する + - featureブランチにコミットを行った人がAuthorになるのではなく、「スカッシュマージ」を行った人がAuthorになる。OSS開発を行う場合など、厳密にコントリビューションを管理する必要がある場合は注意する - GitHubでは「スカッシュマージ」を行う場合、デフォルトでコミットメッセージに `co-authored-by` トレーラーが追加され、1つのコミットが複数の作成者に帰属するようにするようになっている[^2]。この記述は削除しないようにする [^2]: https://docs.github.com/ja/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors @@ -544,7 +542,7 @@ Branch protection rules にdevelop, mainなど永続的なブランチに保護 | | Require linear history | ✅️/- | mainブランチの場合はOFFとするが、developの場合はSquash mergeを求めるため有効にする | | | Do not allow bypassing the above settings | ✅️ | パイパスを許容しない | -開発ブランチに対し「require linear history」を選択することを推奨することで、「Create a merge commit」が選択できないようにする。 +developブランチに対し「require linear history」を選択することを推奨することで、「Create a merge commit」が選択できないようにする。 また、意図しない方法でのマージを避けるためにブランチごとにマージ戦略を設定しておき、想定外のマージ戦略が選択された時に警告色を表示するというサードパーティ製のChrome拡張[^1]も存在する。必要に応じて導入を検討する。