ロジカルなコミットメッセージの書き方
チーム開発におけるコミットメッセージの書き方についてアウトプットします。
コミットメッセージに正解はありません。
組織によって最適な手法は異なるため、参考のひとつにしてください。
要点
フォーマット :Emoji: Title / Reason / Specification / Issue
項目
- Emoji - 内容・種類をひと目で分かるように
- Title - タイトル（概要）
- Reason - このコミットをする理由
- Specification - 言い訳ではなく、このコミット内容になった意図や仕様など
- Issue - 対応するIssue
作業内容はコードを見ればわかるので、「概要」「変更理由」「意図・仕様」を簡潔にまとめる。
例
:seedling: init README.md
:bug: up→down / main.c swap for main.c sort
:wrench: delete secrets / setting.py / issue #3
コミットメッセージを書く理由
そもそも、コミットメッセージを書く理由は以下の通りです。
- ひと目でどんなコミットなのか判断するため
- 簡潔にコミット内容を説明するため
- なぜこのコミットが必要なのか説明するため
- なぜこのようなコミット内容になったのか説明するため
- Issueベースで開発を進めるため
- コードレビューや不具合があった場合の原因追求を助けるため
逆に、コミットメッセージに不要なものは以下の通りです。
- 細かすぎる/大きすぎる仕様・処理の説明 -> Docs（ドキュメント）に書くべき
- 処理の内容 -> コードを見ればわかる
- 言いたいこと、助けてほしいこと -> メンバーにチャットしてください
- 言い訳、独り言 -> Mastdonでつぶやきましょう
ロジカルなコミットメッセージとは
コミットメッセージにおいて重要なことはDocsにも書かれず、コードだけ見てもわからないようなコミットの内容を簡潔に伝えることです。
以上の内容を踏まえて、コミットメッセージに含むべき項目は
- Emoji（コミットの種類） <- ひと目でどんなコミットなのか判断するため
- Title（コミットの概要） <- 簡潔にコミット内容を説明するため
- Reason（コミットの理由） <- なぜこのコミットが必要なのか説明するため
- Specification（コミットの意図・仕様） <- なぜこのようなコミット内容になったのか説明するため
- Issue（コミットに対応したIssue） <- Issueベースで開発を進めるため
ロジカルなコミットメッセージは以下のフォーマットを使用します。
:Emoji: Title / Reason / Specification / Issue
さて、具体的な状況を設定してコミットメッセージを書いていきましょう。
Issue #4であるお問い合わせフォームを実装するために、forms.pyにclient_formクラスを作り、お問い合わせフォーム実装を行った
Emoji
コミットの種類（バグ改善、新機能実装、パフォーマンス向上など）をひと目で伝えることができるのがemojiです。
gitmojiについては既存の有益な記事があるため、そちらを見てください。
Issue #4であるお問い合わせフォームを実装するために、forms.pyにclient_formクラスを作り、お問い合わせフォーム実装を行った
Emojiは「✨（New features）」にしましょう。
Title
コミットの概要はタイトルとして伝えます。
簡潔でわかりやすいタイトルを考えてください。
Issue #4であるお問い合わせフォームを実装するために、forms.pyにclient_formクラスを作り、お問い合わせフォーム実装を行った
Titleは「Set client form」にしましょう。
Reason
「なぜそのコミットを行ったか」という理由を伝えます。
簡潔にコミットを行った理由について書いてください。
Issue #4であるお問い合わせフォームを実装するために、form.pyにclient_formクラスを作り、お問い合わせフォーム実装を行った
お問い合わせフォームを実装する理由は「お問い合わせ対応をするため」です。
Reasonは「for support client」にしましょう。
Specification
「なぜそのコミット内容になったのか」という意図・仕様を伝えます。
ここで注意すべきことは絶対に言い訳を書かないということです。
コード内のコメントにも言えることですが、コメントで言い訳をするようなコード・コメントを見ないと意味がわからないコードは書くべきではありません。
同様に、言い訳をするようなコミット・コミットメッセージを見ないと意味がわからないコミットはそもそもするべきではありません。
このSpecificationはコミットメッセージにおいて重要な要素であるため、ロジカルに書いてください。
Issue #4であるお問い合わせフォームを実装するために、forms.pyにclient_formクラスを作り、お問い合わせフォーム実装を行った
Specificationは「by forms.client_form」にしましょう。
Issue
これは開発手法などによって異なりますが、Issueベースで開発を進めている場合はIssue番号をコミットメッセージに含みます。
Issue番号をコミットメッセージに書いたほうが参照しやすく意図がわかりやすいコミットとなります。
(2023/05/15 追記 nishinoさんより)
書き忘れていましたが、コミットメッセージにIssue番号をつけていると、GithubでIssueとコミットを紐付けることができます。
- コミットメッセージからIssueへ
- Issueからコミットメッセージへ
Issue #4であるお問い合わせフォームを実装するために、forms.pyにclient_formクラスを作り、お問い合わせフォーム実装を行った
Issueは「Issue #4」にしましょう。
完成！
完成したコミットメッセージです。
:sparkles: Set client form / for support client / by forms.client_form / Issue #4
✨ Set client form / for support client / by forms.client_form / Issue #4
しっかりと、:Emoji: Title / Reason / Specification / Issueのフォーマットに適していることがわかります。
逆に不十分なコミットメッセージの例です。
fix: client form
お問い合わせフォーム
form
message
Docsにも書かれず、コードだけ見てもわからないようなコミットの内容を簡潔に伝えることができておらず、コミットの「種類」「概要」「理由」「意図・仕様」「Issue」について触れていません。
個人的な流儀
ここからは一般論ではなく、私の個人的な流儀について紹介します。
emoji/prefixの種類について
使用するemoji/prefixの種類は各自カスタマイズすると良いと思っています。
↓実際に私たちが使用しているprefix
# 🌱 :seedling: Initial
# 🔥 :fire: Update features
# ✨ :sparkles: New features
# ♻️ :recycle: Refactoring
# 🐛 :bug: Bug
# 🎨 :art: Design
# 📚 :books: Document
# 🔧 :wrench: Configuration
# ⚡️ :zap: Improve
# 🚀 :rocket: Deploy
# 🧬 :dna: Merge
# 🧪 :test_tube: Test
コミットメッセージ用の拡張機能などについて
組織や開発手法によってシェルスクリプトや拡張機能等で統一するほうが良いと思います。
多くのgitmoji系拡張機能がありますが、私は紆余曲折した結果、普通にCLIで書いています。
コミットメッセージの長さ
「コミットメッセージは長ければ長いほど良い」という派閥も存在しますが、私はそう思いません。
なぜならコミットメッセージを書く理由は以下の通りだからです。
コミットメッセージにおいて重要なことはDocsにも書かれず、コードだけ見てもわからないようなコミットの内容を簡潔に伝えること
長過ぎるコミットメッセージは簡潔に内容を伝えることができません。
具体的に何文字までという制限はありませんが、私は「1行に収まる自然な長さ」で書いています。
それ以上長いコミットメッセージになってしまう場合はDocsなどに書くべき内容だと考えています。
コミットメッセージは日本語か、英語か
私はコミットメッセージを英語で書いています。
- グローバルなレポジトリにするため
- 語学力向上のため
- 英語の方がロジカルなコミットメッセージを書きやすいから
日本人しか扱うことがないレポジトリであれば日本語でも構いませんが、英語の方がカッコいいです。
この記事を書くきっかけ・参考書籍
私もGitを使い始めた頃は雑なコミットメッセージばかり書いていました。
↓初めての個人開発
しかし、チーム開発でバックエンドを担当した時に、自分の中ではわかりやすいコミットメッセージを書いたつもりが全く理解されませんでした。
その時に言われた先輩エンジニアからの一言がロジカルなコミットメッセージを書くように意識し始めたきっかけです。
お前がわかるコミットメッセージは、お前しかわからない。
誰が見てもわかるコミットメッセージを書け。
これはチーム内のコミュニケーションやマネジメントにも通じることだと思っていて、重要なことは「相手がわかるかどうか」です。
「わかりやすく書こう！」と心がけるだけでなく、「どうすればわかりやすくなるのか」「そもそも何のためにやっているのか」「仕組みづくりから改善できる問題ではないのか」を考えていくことが大切だと思います。
参考
最後に
きれいなコミットを積み重ねてちやほやされましょう！
...
ちや、ほや...?
Discussion
参考
コミットメッセージのルールの1つ。