ブランチの種類表を修正

Author: ma91n

documents/forGitBranch/git_branch_standards.md

@@ -35,14 +35,16 @@ meta:
 
 本規約で想定する、ブランチの種類とその役割を説明する。
 
-| ブランチ名称    | 役割                           | ライフサイクル | 派生元ブランチ          | 命名規則                                              | 直プッシュ可否 |
-|-----------|------------------------------|---------|------------------|---------------------------------------------------|---------|
-| `main`    | プロダクション環境と一致させるブランチ          | 永続的     | -                | `main` 固定                                         | ✕       |
-| `feature` | 特定機能の追加/変更                   | 短命      | `main`／`develop` | `feature/${任意名称}`: 詳細は「featureブランチ」節を参照           | △       |
-| `develop` | 開発の大元となるブランチ                 | 永続的     | `main`           | `develop` 固定。複数必要な場合は `develop2` と連番で区別する         | ✕       |
-| `release` | リリース準備作業の実施                  | 短命      | `develop`        | `release/${yyyymmdd}` や `release/${リリースバージョン}` など | ✕       |
-| `hotfix`  | mainブランチに対する即時修正             | 短命      | `main`           | `hotfix/${任意名称}`: featureブランチに準じる                 | ◯       |
-| `topic`   | featureブランチにて複数人開発をする場合のブランチ | 短命      | `feature`        | `topic/${任意名称}`: featureブランチに準じる                  | ◯       |
+| ブランチ名称    | 役割                | ライフサイクル | 派生元ブランチ          | 命名規則                                              | 直プッシュ |
+|-----------|-------------------|---------|------------------|---------------------------------------------------|---------|
+| `main`    | プロダクション環境へのデプロイ用途 | 永続的     | -                | `main` 固定                                         | ❌️       |
+| `feature` | 特定機能の追加/変更        | 短命      | `main`／`develop` | `feature/${任意名称}`: 詳細は[featureブランチ](#featureブランチ)           | ✅️※1       |
+| `develop` | 開発の大元             | 永続的     | `main`           | `develop` 固定。複数必要な場合は `develop2` と連番にする         | ❌️       |
+| `release` | リリース作業用途          | 短命      | `develop`        | `release/${yyyymmdd}` や `release/${リリースバージョン}` など | ❌️       |
+| `hotfix`  | mainブランチに対する即時修正  | 短命      | `main`           | `hotfix/${任意名称}`: featureブランチに準じる                 | ✅️       |
+| `topic`   | 複数人での機能開発用と       | 短命      | `feature`        | `topic/${任意名称}`: featureブランチに準じる                  | ✅️       |
+
+※1: topicブランチを利用する場合は、派生させたfeatureブランチへの直プッシュはNGとなる
 
 ## mainブランチ
 
@@ -117,17 +119,13 @@ featureブランチで実現する機能を複数人で開発する場合に使
 - できるかぎりシンプルなモデルを選択し、運用コストを下げる
 - プロジェクトのフェーズや体制に応じて、変更を許容する
 
-現実的に利用する可能性が高いブランチの運用パターン３つ示す。
-
-選定を記載順で導入を検討する。
+現実的に利用する可能性が高いブランチの運用パターンを、運用コストが低い順に３つ示す。
 
-- GitHub Flow → Lite GitLab Flow → GitLab Flow
-
-| 名称               | 利用ブランチ                                                                  | 備考                                                                                                            | 運用コスト | 使い所                                                                   |
-|------------------|-------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|-------|-----------------------------------------------------------------------|
-| GitHub Flow      | `main`<br> `feature`                                                    | 最小のブランチ管理パターンで、開発人数が少なく、検証作業は全員で行う場合に有効。<br>マージ毎にプロダクション環境へデプロイする。                                            | 低     | ・個人開発<br>・プロジェクト初期フェーズで断面管理を厳密に行わない場合                                 |
-| Lite GitLab Flow | `main`<br>`develop`<br>`feature`<br>`topic`<br> `hotfix`                | GitHub Flowに`develop`ブランチを追加するパターン（特定の呼称はなくLite GitLab FLowと命名）。<br>`main`ブランチをリリースブランチとし、開発ソースコードとは分ける。    | 低     | ・稼働済みのプロダクトなど、一定品質を保証する必要がある場合<br>・開発作業とリリース作業が並行しないチーム構成である場合 |
-| GitLab Flow      | `main`<br>`develop`<br>`release` <br>`feature`<br>`topic` <br> `hotfix` | GitLab Flowでは`main`ブランチを`production`ブランチ、`release`ブランチとを`pre production`ブランチと呼称するが、本規約では`main`/`release` とする。 | 中     | ・リリース作業と開発作業が並行して行われる場合<br>・断面を指定して複数テスト環境にデプロイしたい場合                |
+| 名称               | 利用ブランチ                                                                  | デフォルトブランチ | リリース作業    | 使い所                                                    | 備考                                                                                                           |
+|------------------|-------------------------------------------------------------------------|-----------|-----------|--------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
+| GitHub Flow      | `main`<br> `feature`                                                    | `main`    | `main`    | ・開発人数が少なく、検証作業を全員で行う場合                                 | マージ毎にプロダクション環境へデプロイする。                                                                                       |
+| Lite GitLab Flow | `main`<br>`develop`<br>`feature`<br>`topic`<br> `hotfix`                | `develop` | `develop` | ・稼働済みのプロダクトなど、一定品質を保証する必要がある場合<br>・開発作業とリリース作業が並行しない場合 | GitHub Flowに`develop`ブランチを追加するパターンで、特定の呼称はないためLite GitLab FLowと命名する                                          |
+| GitLab Flow      | `main`<br>`develop`<br>`release` <br>`feature`<br>`topic` <br> `hotfix` | `develop` | `release` | ・リリース作業と開発作業が並行して行われる場合<br>・断面を指定して複数テスト環境にデプロイしたい場合   | GitLab Flowでは`main`ブランチを`production`ブランチ、`release`ブランチとを`pre production`ブランチと呼称するが、本規約では`main`/`release` とする |
 
 ## 変則的なパターン
 
@@ -320,7 +318,75 @@ Gitにはタグ機能があり、リリースポイントとしてタグを作
 
 これにより、リリースしたアプリケーションやライブラリに何か不具合があれば、切り戻しや原因追求が容易になる利点がある。
 
-タグを利用するうえでの運用ルール・命名規則などは[タグ規則](git_tag.md)を参考にする。
+## タグの運用ルール
+
+- リリースごとに新しいバージョンを示したタグを発行する
+- (推奨) GitHubなどの画面経由でタグを作成する
+- mainブランチにてタグを作成する
+- 入力間違えなどのケースを除き、一度タグをつけた後は削除しない
+- 後述する「タグの命名規則」に従う
+
+![GitHub画面でbackend/v1.6.0のタグを作成する](img/create_new_tag.png)
+
+何かしらの理由で、コマンドラインからタグを作成する必要がある場合は、以下に注意する。画面経由・コマンドライン経由でのタグ作成は混ぜないようにし、運用手順は統一する。
+
+- 軽量 (lightweight) 版ではなく、注釈付き (annotated) 版のタグを利用する
+
+```sh
+# OK（注釈付きタグを利用する）
+$ git tag "v1.0.4" -m "v1.0.4 🐛Fix item api log"
+
+# NG（軽量タグは利用しない）
+$ git tag "v1.0.4"
+```
+
+## タグの命名規則
+
+- `v1.2.4` などの [セマンティックバージョニング](https://semver.org/lang/ja/) を基本とする
+- モノリポの場合は `frontend/v1.0.0`、`backend/v2.0.1` など領域ごとにプレフィックスを付与する形式を取る
+  - プレフィックスにすることで、タグをリスト表示した場合に視認性を上げることができる
+
+命名に従うと、次のようなコマンドで絞り込みで表示できる。
+
+```sh
+$ git tag -l --sort=-version:refname "frontend/v*"
+frontend/v2.0.0
+frontend/v1.3.0
+frontend/v1.2.0
+frontend/v1.1.0
+...
+```
+
+また、Gitクライアントによっては `/` を使うことでフォルダのように階層表示ができるため、プレフィックスの区切り文字は `-` ハイフンではなく、スラッシュとする。
+
+## タグメッセージの規則
+
+- (推奨) GitHubを利用中の場合、「[Generate release notes](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes)」を用いて、タイトルや本文を自動生成する
+- フロントエンド・バックエンドで整合性を保っているのであれば、メモ目的でバージョンを記載する運用を推奨とする
+- 実用的な利用用途が思いつかない場合は、開発者視点での楽しみリリースの大きなマイルストーンの名称など、チームの関心事を記入することを推奨とする
+
+![create new tag](img/create_new_tag_title.png)
+
+何かしらの理由で、コマンドラインからタグを作成する必要がある場合は、GitHub利用時の規則に合わせて次のように作成する。
+
+入力例:
+
+```sh
+# OK
+$ git tag -a backend/v1.8.0 -m "backend/v1.8.0"
+$ git tag -a backend/v1.9.0 -m "backend/v1.9.0 🚀Release with frontend-v3.0.1"
+$ git tag -a backend/v2.0.0 -m "backend/v2.0.0 ✨Android版アプリリリース対応"
+
+# NG
+$ git tag -a backend/v3.0.0 -m "🚀Release version v2.0.0"
+```
+
+## バージョンアップ規則
+
+- 開発しているプロダクトがライブラリの場合、セマンティックバージョニングに厳密に従う
+- 開発しているプロダクトがシステム（アプリケーション）の場合、その成熟度や初回リリースの区切りでバージョンアップを行うことを推奨する。適切なバージョンアップを行うことで視認性が上がり、運用負荷を下げることができる
+  - 例1: 初回リリース、カットオーバーで `v1.0.0` に上げる
+  - 例2: 稼働後1年以上経過し、中規模以上の大きな機能アップデートがあったので、 `v2.0.0` に上げる
 
 # ラベル規則