- Conventional Commits は
<type>[optional scope]: <description> 形式でコミットメッセージに意味を持たせようとするが、変更種別を先に置き、範囲を任意にすることで、実際の探索に必要な情報を後ろへ追いやっている
- コントリビューター・デバッガー・障害対応者はコミットログから変更が触れたコード領域を探すため、バグはどの種別の変更でも生じうる以上、範囲(scope) は種別より重要である
fix(compiler): prevent namespaced SVG <style> elements from being stripped のように説明だけでもバグ修正だと分かり、refactor(core): Update webmcp support to use document.modelContext のように1つのコミットが修正・リファクタリング・機能追加にまたがることもあるため、type は冗長で制約的である- 自動 CHANGELOG 生成とセマンティックバージョンの増分判定は、コミットログと変更ログで読者が異なり、revert・偶発的な後方互換性破壊・後からの破壊解消によって結果がずれることがある
- 範囲プレフィックス のコミットメッセージは変更主体を先に示し、ビルド・デプロイ条件もタイトルの種別より
git diff で変わったファイルを基準にしたほうがよい
間違った優先順位
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
- タイトル行は
fix、feat、chore、docs、refactor のような <type>、任意の scope、description で構成される
- 中核的な欠陥は、変更の主体である scope より、変更の種類である type を優先する構造にある
- scope が任意である構造は、コミットでもっとも重要な情報が欠けうる状態を生み、type をタイトルの先頭に置くことで優先順位を逆転させている
なぜ scope は type より重要なのか
- コントリビューターは、最後の貢献以降の変化、プロジェクト全体の流れ、pull や rebase の際に進行中の作業と衝突しうるコミットを見つけるためにコミットログを読む
- デバッガーは、バグが現れたコンポーネントに関係する領域を触った変更を探すが、バグはどの type の変更でも発生しうるため、type 情報は役に立たない
- 障害対応者は、障害発生時点の前後のコミットログをざっと見て問題を引き起こした領域を探し、インバウンド API エラーが急増した地点に
auth scope のコミットがあれば、有力な原因候補になる
- コミットログを読む人にとって重要なのは、変更がどの種類だったかではなく、どの領域に触れたかである
type の冗長性と制限
自動化の約束の限界
- git-cliff や conventional-changelog のようなツールでコミットから CHANGELOG を自動生成する発想には、コミットログと変更ログでは読者が異なるという問題がある
- CHANGELOG はユーザー向けであり、バージョン間の機能的・ビジネス的な差分を理解することに焦点がある
- コミットログは開発者向けであり、コードベースが時間とともにどう変化したか、scope の観点で流れを読むことに焦点がある
- 中程度以上の複雑さを持つプロジェクトでは、意味のある1つの機能が複数のコミットで導入されることが多く、開発者には実装過程が有用でも、エンドユーザーにとって重要なのは最終的な新機能そのものだけである
- revert コミットは、開発者にとってはコミットログの流れの中で重要だが、エンドユーザーにとっては取り消された変更は最初から作られなかった変更と同じである
- コミット type に基づくセマンティックバージョンの増分は、後方互換性を壊す変更が revert されたのに major バージョンを上げたり、破壊に後から気づいて minor/patch として誤って上げたり、後続コミットと組み合わさって破壊が解消されたのに破壊的変更と判定したりする問題を生みうる
- このような状況では rebase で履歴を修正することもできるが、ワークフローによってはそれが妨げられたり破綻したりし、コミットログが伝える流れの信頼性を下げる
- コミットタイトルの type でビルド・デプロイプロセスをトリガーすると、
docs: fix typos というタイトルのコミットが認証サブシステムに脆弱性を入れる、といった形で自動ツールを回避できてしまう
- ビルド・デプロイ条件は、コミットタイトルより
git diff で変更ファイルを特定して決めるほうがよい
適用上の問題と代替案
- Conventional Commits はプロジェクトごとの type 集合を定義させるが、多くのプロジェクトは commitlint のデフォルト type をそのまま採用しており、個々のプロジェクト特性にうまく合わない可能性がある
- Conventional Commits の仕様は、技術的には
fix と feat だけを定義し、追加の type は各プロジェクトに委ねている
- 企業環境では、変更管理や監査要件により、すべてのコミットメッセージにチケット番号を入れなければならない場合があり、
<scope> がチケット番号の場所として使われると有用な metadata が失われる
- Linux、FreeBSD、Git、Go、NixOS、Node.js は、プロジェクトに適した scope プレフィックスのコミットメッセージを使っている
- Linux カーネルでは subsystem、Go プロジェクトでは package path、マイクロサービスアーキテクチャでは microservice 名が自然な scope になる
- scopedcommits.com は、コミットメッセージを scope 中心の形式へ戻し、CHANGELOG 生成とコミットログ管理を分離しようという方向性を扱っている
- Conventional Commits の利点は実際の利益につながらず、オープンソースプロジェクトでの人気と AI のデフォルト選好傾向が、アンチパターンを含むコミットメッセージの拡散を招いている
2件のコメント
Hacker Newsの意見
プログラマーは、タブとスペースのような些細なことに至るまで、何が最適な設定なのかをいちいち議論して不満を言いがちな気がする
Conventional Commitsがコミットメッセージを構成するための神託のような最善策だと言いたいわけではないが、決まった構造があり、コミットメッセージへの期待値をそろえることのほうが、はるかに効果的で重要だと思う
筆者はスコープがタイプより重要だと強く主張しているが、
fix(compiler)とcompiler fixの違いは、そこまで命を懸けるような話ではないと思う技術業界には、最適ではなくても標準になったものが多くあり、たとえばJSONも最初から作り直すなら、コメントやより明確な数値形式などをサポートすべきだと考える人は多いだろう
それでも以前のものより多くの文脈で優れていたから標準になったのであって、Conventional Commitsと少し違うより良い形式があり得るとしても、コミットメッセージの構造をめぐって別の競合方式を作るほど良いとは思えない
コミットメッセージは、構造が緩くても変更の性質をうまく伝えられれば優れているし、逆に非常に構造化されていても混乱を招いたり情報がなかったりすることがある
全体として筆者に同意で、Conventional Commitsは質の悪いコミットメッセージという根本的な問題を解決していない
XMLも十分に良くて標準だし、SOAPも十分に良くて標準だ
Conventional Commitsは十分に良く、十分に標準化されているので別の構造を検討する価値はない、という話だが、その「価値」は主観的だ
毎日コミットしPRを読むなら、Conventional Commits形式が生む小さな摩擦も積み重なる可能性があり、これを自然法則のように見なさず別の選択肢を残しておけば、それを好むチームには役立つ
そもそも大半のチームは変更ログを生成していない
スコープが重要なのはその通りだが、コミット内容から導き出せるのではないかと思う
diffをレビューするときに変更されたパスを見るのは重要なsanity checkであり、「test」のdiffが本番認証コードを変更してはいけない
それでも
--onelineで見たいなら、feat(auth):のほうがfeat:より良いと思う想定読者が間違っているという主張には同意しない
featコミットは実際にプロダクト観点の変更を説明すべきで、意味の薄いリファクタリング変更を先にきちんと積み、その上に小さな新機能の変更を載せる形に整理すべきだdiffの説明に入れるものとして最も有用なのもこれであり、「なぜアルゴリズムXを選んだのか」といった技術的文脈は、失われないようコメントや
DECISIONS.mdに入れるべきだ動きの速い会社でコミット履歴にこうした地味な作業まできちんと残すのは執着の強い人たちだけかもしれないが、オープンソースプロジェクトではコミットメッセージに文脈を埋め込んでおくことの重要性ははるかに高いと思う
Markdownやプレーンテキストのような形式があり、JSONだけしかないわけではないのには理由がある
タイトルが
small fixだったのに、実際にはまったく小さな修正ではないコミットをあまりにも多くレビューしてきた本当の結論は、プロジェクトごとに要件が異なるということ。
30年以上ソース管理を使ってきたが、説明にコンポーネント（記事では scope と呼んでいる）を標準化された形で入れることが役に立つ作業をしたことは一度もない。
影響を受けたファイルがソースツリーのどこにあるかを見るだけで、どのコンポーネントが変わったかは明らかだし、
bug、fix、featureも有用な価値を追加しない。重要でなければチェックインされなかったはずだ。
役に立つと感じた唯一のものは、記事でまったく触れられていない関連する変更要求へのリンクや ID だ。
コミットには何が変わったかの情報はすでに入っていて、欠けているのはなぜ変わったのかという文脈だ。
個人プロジェクトでも、説明の前の角括弧の中に JIRA 参照を入れ、開発中にたまたま直すことにしたことでも短い1行の JIRA を作って ID を取り、そこに理由を書く。
「なぜ」を捉えることこそがそのメッセージの全目的であり、外部のいつか消えるかもしれないリソースへのリンクを1つ貼るのは良い代替にはならない。
GitHub Issues なら、コミットから PR の議論へ戻ることができ、その PR には関連する Issue や他のポインタがあるべきだ。
もちろん GitHub Issues に移る中で JIRA はほぼ捨て、数年後にはインスタンスが停止して削除された。
今ではその JIRA タグはすべて無価値になっている。
だからむしろ、Issue トラッカーと git リポジトリの強い結合が必要だと思う。
本当に欲しいのは移植性だが、強い結合なしにどうやって得られるのかは分からない。
理想的には公開標準の形式があるべきだが、現実には GitHub が形式を定義する巨大なゴリラであり、GitLab などのクローンが GitHub のプロジェクトメタデータ、少なくとも PR を取り込めるなら、実質的にはそれに近づく。
とにかく、5年後には使っていないかもしれない Atlassian 製品への固定的で不変なポインタを残す方針は良くない。
むしろ git のコミットが完全に独立して成立し、変更の「なぜ」に関するすべての情報をコミットメッセージやソースコメントに溶け込ませるべきだという方針を受け入れる。
ただ、それも失敗すると見ている。人は git のコミットでは短く書きすぎるし、Issue を要約する際に情報を失うし、PR 議論の往復には、変更理由を一人の声で要約した以上の内容が含まれていて有用だからだ。
新機能を先にまとめ、その次にバグ修正を置けば、非技術系ユーザーにも少し読みやすくなる。
コミットメッセージは変更ログ生成のためではなく、未来の開発者のためのものだ。
その開発者がコミットメッセージを読む主な瞬間は、そのコミットがなぜ存在するのか理解できないときだ。
何を変えたかではなく、特定の行の目的が何なのかを知りたい状況だ。
だから
blameを実行してコミットを見に行くが、元の開発者はすでに会社を去っており、昔の JIRA も消えているかもしれず、唯一の手がかりがコミットメッセージになる。https://dev.to/splix/the-why-behind-the-code-2bb1
コミット本文に文脈を入れればいいのではないか?
Conventional Commits を使う多くの人の
choreという言葉には、いつも引っかかっていた。個人的には、ここでも幸い触れられているLinux kernel スタイルのコミットタイトルを好んできた。
[0] https://www.kernel.org/doc/html/v7.0/process/submitting-patc...
choreが示唆する態度には強い嫌悪感がある。それ以外は全部
funやindifferentとでも表示すべきかのように感じられ、そうした感情的な判断はコミットメッセージに入れるべきものではない。upkeep同じ意味だが、軽蔑的なニュアンスはない。
しかも、コミットの全体的な影響を事前に分かっているふりをしていることにもなるが、実際には分からない。
Conventional Commits があると、チームメンバーもLLMも、そのばかげた命名法をひねり出すのに時間とトークンを使うことになる。
Conventional Commits に対する主な不満は、コミットタイトルにIssue 番号が含まれないことだった。
標準文書でも選択肢としてすら触れられていない。
私にとっては、コミットメッセージの中でほとんど最も重要な情報だ。
過去15年間で、古いコミットが参照している Issue の説明を照らし合わせて変更の全体的な文脈を把握したことがどれだけ多かったか分からない。
この習慣は一種の標準なのだと感じていたが、Conventional Commits を知ってから、そうではないと学んだ。
なぜ人気があるのかまったく理解できなかった。
個人的には、Issue はgit trailerとして入れるほうが好みだ。
fix thing in fooIssue: ABC-123Git にはこの種の trailer を解析・整形する組み込み機能が多くあるので、インラインで見たり CI で使ったりするために解析するカスタム
git logエイリアスを簡単に作れるすでに文字数制限のある変更ログをざっと見ているなら、メインのコミットメッセージに
XYZ-999999があることにはあまり関心がないtrailer でタグ付けするのはよいが、Jira の issue 番号よりも、そのコミットが何をしたのかのほうをずっと見たい
issue key をタイトルのいちばん先頭に必ず置くよう要求する場合にだけ問題だと思う
それも可読性には悪いと思う
Conventional Commits の雑多な形式のどこかにただ付けるだけではなぜだめなのかわからない
issue key は英数字の接頭辞の後に数字が続くような正規表現で取り出せるはずなので、こうした「標準」が別の場所を用意する必要はほとんどない
個人的には Conventional Commits なしで、その issue に関連するコミットなら末尾に括弧付きで入れる
issue を修正するような、より強い関係ならメッセージに
Fixestrailer も一緒に入れる面白いね
私たちはこれまで
fix(ABC-123): some message hereのように書いてきたが、リンクもきちんと張られ、自動リリースノートでもとても見やすくレンダリングされるそれは標準ではなく 慣習 だ
チーム内で ticket ID をコミットメッセージに含める標準を決めればよい
機械が読めるようにしたいなら footer/trailer を使えばよい
Conventional Commits についてはよく言えることがない
形式がメッセージの中で最もよく読まれる部分のスペースを占有し、カテゴリや type は情報量が少ない
タイトルに率直な英語の動詞を文のように入れれば置き換えられるし、
:,(),!のような 3 種類の句読点より、普通の文のほうがずっと読みやすいタイトル中の「領域」程度なら許容できるし、それもこの慣習より前からあった
職場では非技術ユーザー向けの Web アプリを作っており、そうしたユーザー向け変更ログはノルウェー語でうまく書ける
コミットメッセージはユーザーには無関係であり、すべてのコミットが最終ユーザー向け変更ログに入るほど良いものでなければならないと要求されることは、私たちには当分なさそうだ
代わりに footer/trailer を使えばよい
Conventional Commits が本当に役立つのは 継続的デプロイ だ
mainにマージされるたびに自動で SemVer タグを付けてデプロイできるが、タグ付けとバージョン管理に必要な判断は、開発者がコミットメッセージを書く時点ですでに行っているからだLinux kernel のような巨大プロジェクトには向かないという点は十分認める
しかし 99% のプロジェクトでは、Conventional Commits と SemVer を組み合わせれば、現在のリリースプロセスより大幅に改善され、自動化しやすくなる
git tagsに依存するやり方が好きだgit describeは継続的デプロイのバージョン管理には十分なことが多く、v1.2.3-4-gabcdefはコミットを Git が満足するほど正確に記述しつつ、SemVer にも似ているので期待値を設定できる新しい
git tagsを人間の判断でのみ付ける場合、たとえばこれは破壊的変更だから今ここで新しいメジャーをタグ付けすべきだ、といったときには特にそうだgit describe形式のバージョン番号で実質的な論点は、SemVer の期待によりよく合わせるために最初のダッシュをプラスに変えるかどうか程度であり、パッケージマネージャでバージョンを正しく並べるなど、SemVer の期待を強制する側に価値があるなら、簡単な正規表現で変換できるgit describeは CD 自動化が容易だが、コミット履歴の魔法のキーワードで推測するより、git tagの選択や GitHub Releases を通じてバージョン番号の決定を人間に残せる職場では、変化に関心を持つ対象に応じて「タグ」も強制している
ここでのタグは git タグではなく PR タイトル内の文字列で、その「タグ」をもとに各チーム向けの変更ログを生成している
そんな妙なやり方でバージョンを付けたいなら、コミット本文に魔法の文句を入れればよい
そうすれば 1 語に制限されることもない
こういうタイトルスタイルはかなり嫌いだ
「Stop something」のような表現はとても人気があるようだが、命令調で「自分が確実に正しい」という感じを与える
なぜ「In favour of something」や「A case against something」のようにしないのかわからない
その立場に同意する必要はないが、表現を弱めろと求めるのは弱い対応だ
considered harmfulほどひどくはないが、それでも少し毒がある要点は、A と B の順番を入れ替えたいといった任意の個人的嗜好のようなものを、実際以上に大きく見せようとしているように見えることだ
多くの人には無礼だが、注意経済 はそういうやり方に報いる
修正: タイトルをより挑発的でないものに変えたようだ
よいことだ
Conventional Commits はあまり好きではないが、人にはそれぞれ好きなものを使わせておけばよい
この種のタイトルの一部に影響を与えたミームがある
変だと思う
このスタイルのコミットメッセージを書く主な理由は CI/CD 自動化 だ
修正: 最初に読んだとき、この部分を記事内で見落としていたが、ちゃんと扱われていた
すまない
コミットタイプが先頭に来るのは、自動化されたワークフローにそのコミットをどう扱うべきか伝えるためだ
たとえば CD をしているなら、
fix:だけをいくつもコミットした場合はセマンティックバージョニングのパッチ番号だけが増えるfeat:をコミットするとマイナーバージョンが上がり、feat!はメジャーバージョンアップになるリリースに CD を使っていなくても、セマンティックなコミットメッセージは変更ログ生成の自動化にも使われることがある
もちろん変更ログには、普通は Git のコミットメッセージそのものを入れるべきではない
そのメッセージはユーザーではなく開発者に向けたものだからだ
セマンティックバージョニングはロールバックで破綻し、自動変更ログは 対象読者 が間違っている
今は SemVer の代わりに CalVer を使っているので問題にはなっていないが、賢い自動バージョン増加という発想自体は気に入っている
コミットタイトルに
fixやfeatがあっても、ログをざっと見る人に有用な情報は与えないAI がコミットをもっと簡単に作れるようにするために Conventional Commits をなくすべきだ、って話じゃないか
順序を逆にすれば、自分の主な不満は実際に解消される
そもそも 機能 って何なんだ？
refactor(core): Update webmcp support to use document.modelContext書き手の言う通り、修正・改善・単なる整理の境界はあいまいで、それぞれの意味的変更を別々のコミットに分ける作業は、どうせ後で squash されるかもしれず、誰の得にもならない仕事を増やすだけだ
Conventional Commits は、別の問題を直接解決するというより SemVer 自動化 を試みた結果生まれた副産物だと思う
変更ログはどうせ自動化すべきではないと思う
一覧が必要なら
git logを見ればいい変更ログは、より広い読者に内部で実際に何が起きているかを伝える機会だ
「変更ログの読者はコミットログの読者と完全に異なる」
「変更ログはユーザー向けだ」
その船はもう出た気がする
たいていの会社は「Bug Fixes & Performance Improvements」で満足している
少なくとも手間をかけないつもりなら、生成された変更ログでもないよりはましだ
uv:を付けることだったそうすると毎週それらを検索して、文面をそのまま使うか少し手直ししていた
製品自体の Help/Release-notes メニューにも載せていた
自分でもやっていないし聞いたこともないことをやめろと言うのは、ちょっと滑稽だ
たいていはデータベーススキーマのマイグレーションや、ほかの重要なものにだけ特別な接頭辞を付ける
コミット名の付け方も下手そうだし、おそらくシンボル名の付け方も下手だろう
実力の問題で、公の場で嘆いているだけなので、放っておけばいい
Lobste.rsの意見
conventional commits への反論を、本能的な拒否感ではなく論理で整理した文章なのでうれしい。
なぜ嫌いなのか深く考えたことはなかったし、LLM が生成したコードと結び付けてしまうからかと思っていた。特に
chore:がいちばん嫌いで、ハンガリアン記法を再発明しないでほしい。そもそも生まれるべきではなかった。chore:は、もはや Angular コミットスタイルガイド にもなく、曖昧すぎると気付いたのかbuild:に吸収された。Angular スタイルにあった時代でも
chore:の説明はかなり具体的な用途を示していたが、一部のオープンソースプロジェクトでは、文字どおり面倒な雑務のように感じる作業へ雰囲気で付けているように見える。conventional commits は好きではないが、提案された代案は scope が任意である理由 を見落としている気がする。
はっきりしたモジュールが多くない小さなプロジェクトでは、「scope」という概念はあまり有用ではない。どちらも見落としている有用な慣行として、コミットタイトルに issue やチケット番号を入れると変更の追加コンテキストを把握しやすくなり、特にコードレビューで役立つ。ただしチケット番号を必須にすると、些細な変更にも無意味なチケットが量産されるので嫌だし、特定のバグや作業を扱う変更なら、そのバグや作業に結び付いているべきだ。
タイトル行を見ただけで分かるべき重複したコミットの「type」よりは、依然としてましだ。
変更がチケットと明確に対応しているなら「チケット番号」コミットを使い、そうでなければ別のやり方を使えばよい。ある変更は type にはよく合っても scope にはあまり合わず、その逆もあるので、scoped commits と conventional commits を混ぜて使うこともできる。
「段落テキストには 等幅フォント を使うな」と言いたい。
それでも、記事の前提にはおおむね同意する。
コミットメッセージがいまいちでも、変更範囲の感触をつかむには
git log --name-onlyやgit log --statをよく使ってみるのを勧める。ファイル名を見ると、各コミットをいちいち全部開かなくても何が変わったのか知るのにかなり役立つ。
本当に気に入っているやり方は、PR タイトルに conventional commit スタイルを強制することだ。
PR タイトルはマージ後でも maintainer が修正でき、コミット履歴を書き換える必要もなく、release-drafter のようなツールと組み合わせれば GitHub リリースで意味のある変更ログを自動化できる。筆者が言うステークホルダーに合った適切な粒度、つまり機能・修正・互換性破壊を分けて見せられ、次の GitHub リリース草案の妥当な semver も自動で処理してくれる。
parse-libのようなコンポーネントが任意であってはならないという記事の指摘はそのとおりだし、conventional commits を強制すると新規貢献者が萎縮するという点にも同意する。しかし代案が特に優れているわけでもない。それでも、互換性破壊識別子である
fix!(parse-lib): Don't leave sparse holes when parsing JSON arraysはかなり多くの情報を与えてくれる。特定コンポーネントのバグ修正であり、その修正に不可避に伴った互換性破壊であり、minor semver 増加のような意味を含んでいる。こういうものは PR タイトルに使える。コミット規律を促す手段として conventional commits にのめり込みすぎて、結局は習慣として固まってしまったことは認める。
今ではしばしば制約的で恣意的だと感じる。いくつかのプロジェクトでは、それが本当に実践的な慣例なのかも分からず、Linux/Go/Node スタイルに近くなってきたが、設定が多様な monorepo では type を無理に作るより
[service]: [what changed]と書くほうが自然だった。今後は厳格な慣例に合わせるより、何が有用そうかを基準に個人のコミットスタイルをもっと試してみるつもりで、scoped commits はよい出発点に思える。chore(lobsters): add my 2 cents on conventionals commits [JIRA-69420]ほぼ全面的に同意するが、「コミットログが語る物語の信頼性を下げる修正主義的な記録を貢献者に見せる」という部分だけは少し見方が違う。筆者は主に公開ブランチのことを言っているようで、公開ブランチなら妥当な助言だ。しかし非公開ブランチには当てはまるべきではない。最終的な変更をレビューする人、つまり maintainer や 10 年後の自分が理解しやすい形にすればよく、前後のつながらない思考の流れや、もっと悪く言えば
address reviewコミットの束を残す必要はない。「なぜ scope が任意なのか？」への答えは、小さなプロジェクトでは単に プロジェクト全体が scope だからだ。
コミットの「type」がそれほど有用でないという点には同意するが、scoped commits と conventional commits の間に大きな違いがあるのかはよく分からない。scoped は「type」を抜いた conventional にすぎず、fix・feat・refactor・chore の区別があっても別に構わない。
みんなが commitlint のデフォルトをそのまま持ってきているだけなら、人々がそれをうまく扱えるようにすればいいだけではないか、と思う。