こちらはNRI OpenStandia 24日目の記事となります。
つまりこの記事はクリスマスイブに投稿されるわけですね。あ～ちょっと鬱。
はじめに
チームで開発しているとコミットメッセージの形式が開発者によってバラバラになることがあります。
また、開発者や状況によってコミットメッセージの情報量が異なったりします。
例えば以下のようなログは情報量がめっちゃ少なくて困ります。
commit <commit-id>
Author: Fuga太郎 Hoge山 <f-hoge@hoge.co.jp>
Date: Fri Dec 13 14:46:30 2024 +0900
リファクタリング
多分Hoge山Fuga太郎くんはめっちゃ急いでリファクタリングしてたのでしょうね。
でも、これだとどこをどう変えたのかあんまり読み取れないですね、困った。
そこでConventional Commitsという簡単な規約を導入し、よりリーダブルなコミットメッセージを目指します。
また、Conventional Commitsを使うとsemantic-releaseによるバージョン管理やcommitlintによるコミットメッセージのチェックが可能となります。
特にsemantic-releaseはリリースノートやCHANGELOGの自動生成を行ってくれ、非常に強力です。
Conventional Commits
Conventional Commits の仕様はコミットメッセージのための軽量の規約です。 明示的なコミット履歴を作成するための簡単なルールを提供します。この規則に従うことで自動化ツールの導入を簡単にします。 コミットメッセージで機能追加・修正・破壊的変更などを説明することで、この規約は SemVer と協調動作します。
Conventional Commitsはコミットメッセージの規約です。
Angularプロジェクトのコミットメッセージの規約から派生したもので、現在ではVue.jsなど有名なプロジェクトにも採用されています。
Conventional Commitsでは以下の形式に沿ってコミットメッセージを書きます。
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
- type
変更内容の種類を示します。以下のようなtypeが良く使われます。- feat : 機能追加
- fix : 修正
- docs : ドキュメント変更
- optional scope
変更箇所のスコープをオプションで記載できます。
特にモノレポで運用しているときに真価を発揮します。 - description
コミットの説明です。
基本的にデフォルトのコミットメッセージとあんまり変わらないです。 - optional body
descriptionの詳細をオプションで記載できます。 - optional footer(s)
破壊的変更を示すBREAKING CHANGEやRefを記載できます。
BREAKING CHANGEはtypeやoptional scopeの後に！をつけることでも示せます。
以下に簡単な例を示します。
feat: add JWT authentication
fix(frontend)!: remove support for legacy authentication methods
feat(api): rename '/user' endpoint to '/users'
The '/user' endpoint has been renamed to '/users' to align with RESTful conventions.
BREAKING CHANGE: Existing clients must update their API calls to the new endpoint.
Conventional Commitsに沿ってコミットメッセージを書くとログが見やすくなったことが確認できると思います。
また、Conventional CommitsのVSCode拡張を使うと気軽にConventional Commitsに沿ったコミットメッセージが作成できるのでここで紹介します。
VSCode Extension
インストール
Name: Conventional Commits
Id: vivaxy.vscode-conventional-commits
Description: 💬Conventional Commits for VSCode.
Version: 1.26.0
Publisher: vivaxy
VS Marketplace Link: https://marketplace.visualstudio.com/items?itemName=vivaxy.vscode-conventional-commits
VScodeのExtensionsの検索フォームに「Conventional Commits」と入力して、いつも通りインストールするだけです。
インストールに成功すると、コミットボタン右上に〇ボタンが新しく追加されます。
使い方
- コミットする際に前述の〇ボタンを押下します
- 〇ボタンを押すとVSCode中央上に入力フォームが表示されます。
まず、コミットメッセージのtypeを選びます。
前述のfeatやfix以外にもrefactorやbuildなどが選べます。
- 次はscopeを入力します。
scopeの選択肢はデフォルトでは何も用意されていないので利用する場合は新規作成しましょう。
一度新規作成すれば次回コミット時から選べるようになります。
- gitmojiを選びます。
Conventional CommitsのVSCode拡張ではgitmojiをコミットメッセージに含められます。
gitmojiはコミットメッセージで使用できる絵文字です。
コミットメッセージが視覚的に分かりやすくなるため、自分は絶対入力するようにしています。
- ログの概略を入力します。
1行で簡単にログの説明を入力します。
- ログの説明を入力します。
概略で説明できなかった詳細を入力します。
- コミットメッセージのフッターを入力します。
BREAKING CHANGEやRefを入力します。
Git Graphでログを確認してみます。
ちゃんと入力値がコミットメッセージに記載されてますね。
また、gitmojiがレンダリングされているのが確認できると思います。
1ログではConventional Commitsの破壊力が分かりにくいのですが、実際の開発でログが乱立してくると真価を発揮するので皆さんぜひ導入してみてください。
最後に
前述の通りConventional Commitsはcommitlintやsemantic-releaseと組み合わせることでより真価を発揮するのですが、それを書くのには時間余白が足りないので皆さんにお任せします。
この記事を書いていてコミットメッセージさえ書くの面倒だと感じたので、次はgithub copilotにコミットメッセージを書かせてみようかな...。