🧜‍♀️

ソースコード管理可能なMermaidでブランチ戦略図を描く（Zenn, Github）

2024/05/05に公開

GitHub

概要

様々なプラットフォームで手軽にUMLを描くことができるMermaid。ブランチ戦略図を描く際にとても便利だったので、紹介します！

できること

Mermaidは、マークダウン形式のドキュメントに埋め込むことができます。
筆者が活用しているのは、次の２つです。

Zennの記事への埋め込み
Githubリポジトリへの埋め込み

Zennの記事への埋め込み

Mermaidは、Zennの記事に埋め込むことができます。
何を隠そう、こちらの記事に埋め込んでいるブランチ戦略図もMermaidで書きました。

記事の編集画面には、下のようなソースコードを埋め込んでいます。

```mermaid
gitGraph
  commit
  branch hotfix order:1
  branch release_1 order:2
  branch feature_1_1 order:3
  checkout feature_1_1
  checkout hotfix
  commit
  checkout main
  merge hotfix tag: "v0.1"
  checkout release_1
  merge hotfix
  checkout feature_1_1
  commit
  checkout release_1
  merge feature_1_1
  checkout main
  merge release_1 tag: "v1.0"
  branch release_2 order:4
  checkout release_2
  branch feature_2_1 order:5
  checkout feature_2_1
  commit
  checkout release_2
  merge feature_2_1
  checkout main
  merge release_2 tag: "v2.0"
'''

Githubリポジトリへの埋め込み

GithubリポジトリのWikiやREADME.mdにも埋め込むことが可能です。
ブランチ戦略は、図示することでイメージをつかみやすく、格段に理解が深まります。
チーム開発において、ブランチ戦略のイメージが共有されていないことは致命傷になりえるので、図示することはMUSTと言えます。
筆者は、ブランチ戦略を図示するにあたり、Mermaidの活用をおすすめします。

GithubリポジトリにMermaidを勧める理由

修正の手軽さ

ブランチ戦略は、状況により柔軟にアレンジを加えていくものだと考えています。
アレンジを加えた際には、それをチームメンバーに共有する必要がありますが、その際にMermaidでコードを埋め込んでいれば、手軽に修正・共有することができます。

この「手軽さ」というのは思いのほか重要です。
スケジュールに追われる開発においては、ドキュメントのメンテナンスは後回しにされがちです。
ドキュメントのメンテナンスを怠ると、少しずつチーム開発がほころびはじめます。
気づいた時には手遅れ、リカバリに多大な労力が必要になる、という事態を防ぐために、気づいた時に「手軽に」メンテナンスできることは重要なのです。

修正履歴が残る

図をソースコード管理することで、修正履歴を残すことができます。
図そのものを管理している場合は、変更前後の図を見比べないと修正箇所がわかりませんが、ソースコード管理していればdiffで確認することができます。

Mermaidでブランチ戦略図を描くコツ

Mermaidの導入当初、思うように図が描けず、苦労しました。
引っかかったポイントを基に、Mermaidでブランチ戦略図を描く上でのコツを残します。

基本となるブランチはmain固定

ブランチ戦略によってはmasterと表記されることもありますが、Mermaidにおいてはmain固定のようです。
また、最初にcommitが必須なのも、引っかかりポイントです。

```mermaid
gitGraph
  commit
'''

新たに登場するブランチは宣言が必要

新たに登場するブランチは、branchによる宣言が必要です。order:で順番を指定することもできます。

```mermaid
gitGraph
  commit
  branch feature order:2
  branch hotfix order:1
'''

実際の開発の流れに沿うことを意識する

図を描く際は、実際の開発の流れに沿うことを意識すると、スムーズに描画できます。
例えば、緊急のバグ修正の際に、hotfixブランチを使って修正する場合は、次の流れで修正します。

hotfixブランチにチェックアウトする
修正をコミットする
mainにチェックアウトする
hotfixをマージする

これを図示すると、次のようになります。

ソースコードは次のとおりです。実際の開発の流れに沿っていることがわかります。

```mermaid
gitGraph
  commit
  branch hotfix order:1
  checkout hotfix      ・・・1. hotfixブランチにチェックアウトする
  commit　　　　　　　　　・・・2. 修正をコミットする
  checkout main　　　　 ・・・3. mainにチェックアウトする
  merge hotfix　　　　　・・・4. hotfixをマージする
'''

これに気付くまで思い通りに描くことができませんでしたが、これに気付いた後はサクサク描くことができるようになりました。

おわりに

開発、というとプログラミング言語やフレームワーク等にスポットが当たることが多いですが、ドキュメント整備に気を配ることも大切です。
よりドキュメント整備しやすい便利なツールがたくさん出てきていますので、これからもアンテナを張って情報収集し、開発に活かしていこうと思います！