コミットメッセージの書き方をある程度決めておくことの重要性

エッセイ記事です。最近は英語の技術文書方言を作る構想を練っており、その参考として、筆者が普段コミットメッセージを書くときにふんわりと採用している文体を意識化しておこうと思い、つらつらと書いてみます。あえて記事にするのは、特に「こうすべき」ということではなく、タイトルにもあるとおり「何らかのスタイルを決めておくと楽」ということを伝えたい、みたいな意図もあります。

Conventional Commits

Conventional Commitsは、（言わずと知れた）コミットメッセージの書き方に関する慣習です。筆者は必ずこれに従って書いています。これに馴染みのない読者のために、極端に簡略化して例示すると

feat: do some stuff

のようなフォーマットです。featの部分はcommit typeといい、どんなバリエーションを許容するかは究極的にはコミュニティーやプロジェクトに任されていますが、よく使われるものはある程度決まっています（fixとかrefactorとか）。あと重要な点として、commit typeの直後に!を付けると破壊的変更を意味するようになります。詳しくは上記リンク先を参照してください。

これの何が嬉しいかというと、リリースの際にセマンティックバージョニングでのバージョン番号を自動的に算出できることです。対応しているソフトウェアはたくさんありますが、筆者は主にconvcoを使っています。convco version --bumpみたいにコマンドを叩くと次のリリースに適切な番号をコミットログとバージョンタグから自動で算出して出力してくれるという絡繰です。

機械可読なものを人間が書くとなると、それをリンティングしたくなるというのが自然な欲求であり、もちろんそのためにcommitlintというソフトウェアがあります。セットアップが面倒なので筆者はほぼ使っていませんが、手間を考えないのであればあらゆる自分のプロジェクトでこれがあったらいいなと思います。

文体

Conventional Commitsを使っても、結局description（上記例の“do some stuff”にあたる部分）は自由に書くことになるわけですが、そこでどのような文体で書くのかは悩ましい問題です。特に世間で侃侃諤諤としているのは時制に関してであり、現在時制か過去時制かで意見が分かれるようです。

筆者個人としては、以下のような独自ルールを設けて基本的にこれに従っています。

1. 英語を使う
2. 動詞の原形から始める
3. 先頭は小文字にする
4. 固有名詞の大文字小文字は公式で使われている表記に従う^[1]
5. コード片やファイル名やURIなど、本来機械可読なものを指している意識があるときは``で括る^[2]
6. 可算名詞の数は、その区別がコミットメッセージの読者にとって重要と思われる場合には注意を払い、そうでなければ基本的に複数形にする^[3]
7. 冠詞は、イディオムの一部であるか、どうしてもそれが無いと意味が通らないか、のいずれでもなければ基本的に省略する
8. 辞書の見出し語にないようなアドホックで中途半端な略語を一般用語として使わない（例えば“documentation”のつもりで“doc”という表現を使わない）^[4]
9. アクロニムを小文字にしない
10. 文は常に一つ
11. 末尾にピリオドを付けない

当然ですが、コミットメッセージの本文（body）を書く場合は上記のルール関係なく普通の英語で書いています。

---

具体的なルールそれ自体が重要なのではなく、何らかの定まった文体が手に染み付いて、コミットメッセージを書こうとしたら勝手に指が動く、というところまで無意識化することが重要なのだと思います。これにはさまざまな利点があります。というより欠点がありません。

1. コミットメッセージを書くときに時制をどうするかなど非本質的なことで悩まなくて済む
2. （1により）何を書くかに思考のリソースをより多く割けるようになり、良質なコミットメッセージに繋がる
3. シェルの履歴に以前使ったコミットコマンドがもうあって大体サジェストしてくれたりする^[5]
4. ほぼ定型表現ばかりになるので、コミットログの一覧性が良くなる

まあ、今となってはコミットメッセージなんて「AIさんなんとかして」案件なのかもしれませんが⋯⋯。

草草

脚注

1. 2があることで固有名詞が先頭に来ることはないので3と競合しません。

2. ブランチ名やバージョン番号は括ったり括らなかったりしてしまっているのでなんとかしたいと思っています。

3. 例えば、スナップショットの内容を更新するだけのコミットなんかは、変更箇所が単数か複数かはほとんど誰も気にしないと思うので、仮に一箇所だけだったとしても“update snapshots”とします。一方、機能追加の数なんかはコミットの分割にも関わる重要な問題であり、“add features”のような複数形のコミットメッセージになるとすれば、適切にコミット分割できていないということがわかるので、その時点で作業内容を複数コミットに分割することになります。

4. ただし、こういった略語とよく似たドメイン固有のマーケティング用表現がある場合は、それを指すときに限りそのまま使います。例えば、Rustの公式で“doc comment”と呼ばれているものを指すときは“doc comment”という表現をそのまま使います。

5. 実は上で挙げたcommitlintを使っていない理由の一つがこれで、タイポしたりするとサジェストが一切出なくなるのですぐに気づけます。