「コミットメッセージ」をわかりやすく書く方法

Last updated at 2021-12-26Posted at 2021-12-24

はじめに

フロントエンドエンジニアをしているズッキーです。
アルバイトを含めるとXHTMLの流行りが終わり始めたぐらいの時代から、フロントエンドエンジニアを経験してます。

さて昔と比べると
昨今のクライアント側のマシンスペックの向上や、
ブラウザ機能の発展に伴い、
「フロントエンドに対する、要件や要求」
が年々上がってきているなぁと感じております。
（とても良いこと）

伴い、複数人でフロントエンドを開発するシーンが増えてきました。

最近はフロントエンドエンジニアチームの組織化を色々頑張っているのですが、その中の取り組みの一つである、コミットメッセージの最適化をご紹介させてくださいませ！

個人的な見解ですが、
**なぜ（why）、どこ（where）の何（what）**を修正したのかが、
ぱっと読み取れるメッセージだと思ってます。

【良くない例】
「バグ修正」
これだと何を修正したのか、第3者がソースコードを見ないとわからない。。👴

【良い例】
「XXXのXXXフィールドの値がない場合に意図しない空白ができるバグを修正」
なぜ（why）、どこ（where）の何（what）が入っていてわかりやすい！☺️

ということで、チームでの開発となると、ルールが必要になりますが、ここでは「Conventional Commits」を紹介します。

明示的なコミット履歴を作成するための簡単なルールです。

【公式ドキュメント】
https://www.conventionalcommits.org/ja/v1.0.0/
※ GitHubのStarは3.6kある（2021年12月24日時点）

下記が公式で紹介されているフォーマットです。
どういう事かわからないと思いますが、詳細は後述するのでまずは共有まで。

【フォーマット】

<型> [任意スコープ] : <タイトル>
[任意本文]
[任意フッター]

【適用した例】

feat(トップページ): XXXのXXXフィールドの値がない場合に意図しない空白ができるバグを修正

XXXフィールド配列が空で返却された場合に、「〜はございません」のテキストを表示するように修正

Refs: #111

例を元に、下記の順番で説明します！

1. 型を指定する
「どういった作業を行ったのか」を型として指定します。

例でいうとfeatの箇所になります。
下記がよく利用される型の認識です。

型	意味
feat	新しい機能を追加したときに指定
fix	バグの修正
BREAKING CHANGE	破壊的な変更
docs	ドキュメントのみの変更
style	フォーマットの変更（コードの動作に影響しないスペース、フォーマット、セミコロンなど）
perf	パフォーマンスの改善のための変更
refactor	リファクタリングのための変更（機能追加やバグ修正を含まない）
test	不足テストの追加や既存テストの修正

2. 任意でスコープを設定する
対象ページや対象コンポーネントなどのスコープを任意で指定します。

例でいうと、(トップページ)の箇所になります。

3. タイトルを記載する
コミット内容の概要を簡潔に指定します。
このときに、「なぜ（why）、どこ（where）の何（what）」を意識して書くと良いと思います。

例でいうとXXXのXXXフィールドの値がない場合に意図しない空白ができるバグを修正の箇所になります。

4. 任意で本文を記載する
コミット内容の詳細を説明します。

例でいうとXXXフィールド配列が空で返却された場合に、「〜はございません」のテキストを表示するように修正の箇所になります。

5. 任意でフッターを記載する
課題番号（Refs）やレビュワー等（Reviewed-by）を指定します。

例でいうとRefs: #111の箇所となります。

ここでは深く説明しませんが、このようなツールをチームで使う事で、チーム内でのコミットメッセージの統一や、規格を守ってもらうための一助となります。
https://github.com/commitizen/cz-cli

フロントエンドが複雑になってきているが、頼もしい仲間と共同で作業できる時間はすごく楽しいです。
これからも力を合わせて、頑張れるように色々な施策を考えて実行できればと思ってます。

読了いただき誠にありがとうございました！
Developer eXperienceの向上に貢献できていれば、
嬉しく思います。