Skip to content

Commit

Permalink
Feature/tip (#154)
Browse files Browse the repository at this point in the history 
* :::tip

* fix work, spinout tag page
  • Loading branch information
@ma91n
ma91n authored Jul 23, 2024
1 parent 6432fc8 commit 80e4216
Show file tree
Hide file tree
Showing 5 changed files with 98 additions and 85 deletions.
92 changes: 10 additions & 82 deletions documents/forGitBranch/Gitブランチフロー規約.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ meta:

develop2のリリースは以下の手順で行う。

1. `develop`から`develop2`へマージコミットによって同期を行う。（2でconflictが起こらないよう、前準備の意味合いで実施する。）
1. `develop`から`develop2`へマージコミットによって同期を行う。（2でコンフリクトが起こらないよう、前準備の意味合いで実施する。）
2. `develop2`から`develop`にmergeを行い、その後は通常のリリースフローに従う
3. 問題なくリリースが完了し次第、`develop2`を削除する

Expand All @@ -79,7 +79,7 @@ develop2のリリースは以下の手順で行う。
インターフェースの大型改善や、仕様変更を受けてversion1からversion2へupdateを行った場合を想定する。
メインの更新はversion2（mainブランチ）に対して行っていくが、version1の利用ユーザーが存在する場合、バグfixやセキュリティアップデートを並行して行うことが考えられる。
そういった場合はversion1を示すブランチ（`support/v1`）を別途作成、そのブランチからfeatureブランチを作成してfixを行う。
featureブランチのマージ後、マイナーバージョン（あるいはパッチバージョン）を上げたtagをcommitし、本番環境へリリースする。
featureブランチのマージ後、マイナーバージョン（あるいはパッチバージョン）を上げたタグをコミットし、本番環境へリリースする。
※この例ではversion1とversion2が別リソースとして動いていることを前提としている。同一リソースで複数バージョンが稼働する場合はversion2のブランチで対応を行う必要がある。

## マージ戦略
Expand Down Expand Up @@ -117,7 +117,7 @@ featureブランチのマージ後、マイナーバージョン（あるいは

- 前提として、別の開発者が行った開発ブランチの変更は、適時機能ブランチに取り込んだテスト実行や動作検証を行うべきである
- 開発ブランチの変更の取り込みをマージで行うと、そのたびにマージコミットが作成され履歴が複雑になるため、レビューアの負荷軽減を目的とする
- リベースによるConflictリスクについては、開発ブランチを取り込む段階でマージ・リベース問わず解消が必要となる
- リベースによるコンフリクトリスクについては、開発ブランチを取り込む段階でマージ・リベース問わず解消が必要となる

開発者は `git pull` 時の挙動をリベースにするよう設定する（`git config pull.rebase true`）。

Expand All @@ -135,17 +135,17 @@ featureブランチのマージ後、マイナーバージョン（あるいは

::: tip

強制プッシュすることにより、レビューコメントが消えてしまわないかという懸念を聞くことがある。2024年7月に実施した下表の調査結果においてForce Push運用による支障は無いと言える。
強制プッシュすることにより、レビューコメントが消えてしまわないかという懸念を聞くことがある。2024年7月に実施した下表の調査結果において強制プッシュ運用による支障は無いと言える。

- 「a.履歴保持」: Force Pushを行い、GitHub投稿したレビューコメントが履歴として何かしらのページで取得できるかどうか。GitHubではConversationタブで確認
- 「b.行単位の紐づけ（該当行の変更なし）」: レビューコメントが付けられた行とは別の変更を行い、Force pushしたときにレビューコメントの紐づけが残るかどうか。GitHubではFile chagedタブで確認
- 「c.行単位の紐づけ（該当行の変更あり）」: レビューコメントで付けられた行を修正し、Force pushした時の挙動。レビュー対応をしたとみなしレビューコメントのひも付きは解除されているべきである。GitHubではFile chagedタブで確認
- 「a.履歴保持」: 強制プッシュを行い、GitHub投稿したレビューコメントが履歴として何かしらのページで取得できるかどうか。GitHubではConversationタブで確認
- 「b.行単位の紐づけ（該当行の変更なし）」: レビューコメントが付けられた行とは別の変更を行い、強制プッシュしたときにレビューコメントの紐づけが残るかどうか。GitHubではFile chagedタブで確認
- 「c.行単位の紐づけ（該当行の変更あり）」: レビューコメントで付けられた行を修正し、強制プッシュ時の挙動。レビュー対応をしたとみなしレビューコメントのひも付きは解除されているべきである。GitHubではFile chagedタブで確認

| サービス | a.履歴保持 | b.行単位の紐づけ（該当行の変更なし） | c.行単位の紐づけ（該当行の変更あり） | 備考 |
|----------------|--------------|---------------------------------|---------------------------------|---------------------------------------------------------------|
| GitHub | 残る | 残る | 消える | |
| GitLab | 残る | 残る | 消える | |
| AWS CodeCommit | 残る | 消える | 消える | Force Push関係なく、最新のコミットに対してのみレビューコメントが紐づく。そのため、新しいコミットをPushすると、過去につけたレビューコメントがファイル詳細から消えたように見える |
| AWS CodeCommit | 残る | 消える | 消える | 強制プッシュ関係なく、最新のコミットに対してのみレビューコメントが紐づく。そのため、新しいコミットをPushすると、過去につけたレビューコメントがファイル詳細から消えたように見える |
:::

### 2. メインの開発ブランチに機能ブランチの変更を取り込む
Expand Down Expand Up @@ -238,7 +238,7 @@ Gitのコミットメッセージは原則自由とする。理由は以下で

## ラベル

TODO ラベルについて方針を追加する。（ラベルを利用することで、issue, pull requestを分類わけすることができる。適切に設定することでリリースノート作成時に有用である。）
TODO ラベルについて方針を追加する。（ラベルを利用することで、issue, プルリクエストを分類することができる。適切に設定することでリリースノート作成時に有用である。）

https://docs.github.com/ja/issues/using-labels-and-milestones-to-track-work/managing-labels

Expand All @@ -248,79 +248,7 @@ Gitにはタグ機能があり、リリースポイントとしてタグを作

これにより、リリースしたアプリケーションやライブラリに何か不具合があれば、切り戻しや原因追求が容易になる利点がある。

タグの運用ルール:

- リリースごとに新しいバージョンを示したタグを発行する
- (推奨) 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クライアントによっては `/` を使うことでフォルダのように階層表示ができるため、プレフィックスの区切り文字は `-` ハイフンではなく、スラッシュとする。

```
![TODO -](VSCodeクライアントで階層表示されている画像.png)
```

タグメッセージの規則:

- (推奨) 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` に上げる
タグを利用するうえでの運用ルール・命名規則などは[タグ規則](git_tag.md)を参考にする。

## 参考1:ローカルでの作業例

Expand Down
6 changes: 3 additions & 3 deletions documents/forGitBranch/each_branch.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ author: フューチャー株式会社

本ドキュメントで想定する、各ブランチの特徴を説明する。

| ブランチ名称 | 役割 | ライフサイクル | 利用シーン | 命名規則 | 直push可否 |
| ブランチ名称 | 役割 | ライフサイクル | 利用シーン | 命名規則 | 直プッシュ可否 |
| -------------- | ----------------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `main` | production環境と一致させるブランチ | 永続的 | すべてのケースで使用 | `main`: 原則変更しない | ✕ |
| `feature` | 特定機能の追加/変更 | 短命 | ほぼすべてのケースで使用<br>個人開発ではmainブランチのみの使用もあり得る。 | `feature/${任意名称}`: 詳細はfeatureブランチの章に記載する | △ |
Expand All @@ -22,7 +22,7 @@ author: フューチャー株式会社
Gitリポジトリを新規作成するとデフォルトで作成されるブランチで、主な特徴は以下である。

- 過去はmasterだったが最近はmainという名称に改名された
- 個人開発であればmainブランチに直接pushして開発することもできるが、チーム開発では直接push禁止でマージを行うだけのブランチとして扱う
- 個人開発であればmainブランチに直接プッシュして開発することもできるが、チーム開発では直接プッシュ禁止でマージを行うだけのブランチとして扱う
- production環境と対応するブランチとなる場合が多い

## featureブランチ
Expand Down Expand Up @@ -92,7 +92,7 @@ fixtypo
featureブランチで実現する機能を複数人で開発する場合に使用するブランチで、主な特徴は以下である。

- featureブランチからtopicブランチを作成し、topicブランチ上で個人の開発を行った後、featureブランチへマージする。（masterブランチ/developブランチとfeatureブランチの関係と同等。）
- topicブランチが必要なケースでは、featureブランチへの直接pushは原則行わない
- topicブランチが必要なケースでは、featureブランチへの直接プッシュは原則行わない
- GitHub Flowではfeatureブランチのことをtopicブランチと呼称する場合があるが、本規約ではfeatureブランチから派生するブランチをtopicブランチと定義する

![topic branch](img/branch_strategy_topic.drawio.png)
Expand Down
85 changes: 85 additions & 0 deletions documents/forGitBranch/git_tag.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
---
sidebarDepth: 4
title: Gitブランチフロー規約 - タグ規則
author: フューチャー株式会社
---

## タグ規則

Gitにはタグ機能があり、リリースポイントとしてタグを作成する運用とする。

これにより、リリースしたアプリケーションやライブラリに何か不具合があれば、切り戻しや原因追求が容易になる利点がある。

### タグの運用ルール

- リリースごとに新しいバージョンを示したタグを発行する
- (推奨) 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クライアントによっては `/` を使うことでフォルダのように階層表示ができるため、プレフィックスの区切り文字は `-` ハイフンではなく、スラッシュとする。

```
![TODO -](VSCodeクライアントで階層表示されている画像.png)
```

### タグメッセージの規則

- (推奨) 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` に上げる
Binary file modified documents/forGitBranch/img/release_overtaking.drawio.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified documents/forGitBranch/img/release_overtaking_hotfix.drawio.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 80e4216

Please sign in to comment.