sh1’s diary

プログラミング、読んだ本、資格試験、ゲームとか私を記録するところ

自分の GitHub コミットメッセージの書き方

この記事は「自分の日本語ルールをつくる」というのと、同じような話です。

GitHub のコミットメッセージをどういう書き方をしたらいいのか(どうしたら読みやすくなるのか、よりよいと言われるのか)、という回答のひとつに プレフィックス(接頭辞) をつけてあげるというのがあります。

  • feat: xxxx という機能を追加
  • fix: xxxx というバグ修正をしています

最初になにをしたのか書いてあげることで、わかりやすくなるやつです。「vscode」のコミットログをみてみると、一文字目に何をしているのかを表す動詞がきていそうです。こんなやつです。

この書き方規約をまとめたもので有名なのが「AngularJS」。これを手本にしたコミットメッセージを紹介する記事は、いくつも見つかると思います。私の記事も今更ですが、これに倣っています。

コミットログの頻出単語から書き方を検討した例もおもしろいです。個人的に、どうしてこう書くのか、という理由のほうを重要視したので規約を採用。(初心者も書き方の理由について納得しやすい)

(私が)使用する規約メモ

<type>: <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

どのコミットメッセージの行も 100 文字におさえる。可読性を大事にする。

Type

  • feat: 新機能
  • fix: バグ修正(バグ修正 or 重篤なバグ修正で程度も明記)
  • docs: ドキュメント操作
  • style: コードに影響を与えない変更 (空白、フォーマット、etc)
  • refactor: コードの内部構造を整理
  • test: テスト関係
  • chore: 雑務全般(その他)
  • remove: 機能停止(無駄な機能を削除)
  • revert: <hash> にコミットを戻す

機能停止をするとき Type の選択に困ったため remove の種類を追加した。

Scope (省略)

影響範囲の記入はしない。書き方の自由度が高いことと、重要性がわからなかった。Scope を採用していない例も多いため、丁寧なコーディング規約と判断して今は記述を省略。

変更したファイルはわかるし、要約で必要なほどではなかった。

Subject

簡潔な説明。現在形を指定。例:追加“した”NG。

  • style: separate selectors and declarations by new lines
  • docs: optimize images
  • fix: allow third-party promise libraries

Body

body も現在形を指定する。以前の振る舞いとの違いを示す。

Added new event to $browser:
- forward popstate event if available
- forward hashchange event if popstate not available
- do polling when neither popstate nor hashchange available

破壊的変更をするときは BREAKING CHANGE で行を始める。 問題の参照先があるなら次の書き方。

  • Closes #****(要望などはこっち)
  • Fixes #****(バグを閉じたときはこっち)

例文

1

feat($browser): onUrlChange event (popstate/hashchange/polling)

Added new event to $browser:
- forward popstate event if available
- forward hashchange event if popstate not available
- do polling when neither popstate nor hashchange available

Breaks $browser.onHashChange, which was removed (use onUrlChange instead)

2

fix($compile): couple of unit tests for IE9

Older IEs serialize html uppercased, but IE9 does not...
Would be better to expect case insensitive, unfortunately jasmine does
not allow to user regexps for throw expectations.

Closes #392
Breaks foo.bar api, foo.baz should be used instead

更新・改定

文章ルールとは違って、プロジェクト単位で一貫性は保たれていたほうがよいと思っています。ただ、スタイルの更新・改定はあったほうが便利。

A foolish consistency is the hobgoblin of little minds, adored by little statesmen and philosophers and divines.

コミットメッセージにフォーマット規約を用意して記述するのは、いつどういう変更があったのかの要約を見やすくするため。書き方を統一して、要約をつかみやすくするため。コミットログのノイズを減らすこと。

ポリシーがないと、書き方がブレたり揺らぐ。

参考