共同開発に使うバージョン管理システムのリポジトリにコミットするみなさんへのおねがいをまとめたものです。開発が長期化してもスムーズな開発（バグ対応含む）を維持することを主な目的としています。筆者はプログラマですが、対象はプログラマに限りません。
具体的なバージョン管理システムが何であるかは関係無く適用できるものにしたつもりですが、いちおう、筆者が想定しているのは Git, Subversion, Perforce あたりです。用語は主に Git を想定しています。別のバージョン管理システムについては用語を適宜読み替えてください。
コミットする前に内容を確認する
変更点の確認を行い、間違った変更、余計な変更、同時にコミットするべきファイルの抜け、などが無いかを確認してください。これは意図しないコミットによるエラーやそれに伴う修正などの面倒を防ぐために必要なほか、適切なコミットメッセージを残すためにも必要になります。各クライアントソフトの提供する、変更点の一覧表示、ファイルの差分表示などを活用してください。
特に、開発サイクルに必要なビルドなどの過程でエラーの出る状態のファイルをコミットしてはいけません。他の人の作業を止めてしまうかもしれないからです。このほか、バグの調査などでバージョンを戻して使う際にもエラーの出る状態のコミットは邪魔になります。
変更の理由をコミットメッセージに残す
時間が経った後にコミットメッセージを見て知りたい情報は「なんでこんなふうになってるんだろう？」「こんなふうにする必要があったんだろうか？」というものになることが多くあります。例えば、変更内容をレビューするとき、バグの原因を探したり対応方法を検討しているとき、他の人の担当箇所を引き継いで既存のファイルを見ているとき、などです。
こんなときに、対応するコミットのメッセージが「～を更新」や「～を修正」だけで終わっていると、欲しい情報を探し出すのは難しくなります。結果として、変更が正しいのか判断できない、バグへの適切な対処ができない、スムーズな引継ぎができない、などの問題につながります。
そんなことの無いように、コミットメッセージから変更の理由が読み取れるようにしてください。変更して間もない、コミットするタイミングで本人が書くメッセージは、変更の理由を残す場所としてちょうどいい場所になります。逆に言えば、ここで意識して残さないと有用な情報が簡単に失われてしまうことになります。
悪い例
ここでいう変更の理由とは「その変更がないと何が問題だった・嫌だったのか？」という問いの答えとなる情報です。ログの文面が「～ので～」「～のため～」などと 理由を書いているような形になっていても、この点を外していては望む情報とはなりません。以下にいくつか、よくある悪い例とそれに対する改善の例を挙げます。
「○○さんから指示されたので A を B に変更」
これでは○○さん本人が「 A を B に変更」というだけのコミットをしたのとほとんど同じです。
指示には理由があるはずですのでそれを書きましょう。「 A だと××になってしまっていたので B に変更」など。これに加えて「○○さんから指示を受けたもの」という事実を添えることに問題はありませんし、有益です。
「バグっていたので～」
どんなバグが起こっていたのか、わかりません。
こんなときは問題の発生条件や症状を書きましょう。「○○のときに△△すると□□になっていたので～」など。
「 A を B にしたほうがいいので～」
何がどう「いい」のかわかりません。時と場合、人によって評価が分かれるかもしれません。
かわりに客観的な事実を書いておけば間違いありません。「 A を B にすると△△を 10% ぐらい節約できたので～」 など。
変更の理由が明らかな場合
プロジェクトの目的や他の資料などで必要性が明らかなものを作成・追加した場合は「～を作成」で済んだり、誤字脱字スペルミスなど、明らかな間違いに対する修正なら「～を修正」で済むこともあります。これらは「その変更がないと何が問題だった・嫌だったのか？」という問いに直接答えるものになるからです。
ただし、ここでの「明らか」というのは 自分以外の人や、数週間後の自分にとっても「明らか」であるということです。簡単なログで済ませたいと思っていると見誤る可能性があるので、気をつける必要があります。
変更の理由に関する参照
関連する課題、バグ、要望などの ID や URL を参照としてコミットメッセージに残しておくと、あとで変更の理由・経緯をたどる時にとても役に立ちます。当てはまる場合は忘れずに書き残すようにしてください。
変更の理由・経緯が参照先で確認できるならコミットメッセージを簡素に済ませても問題無くなることがあります。ただし参照先が消えたりアクセス権が限られたりする可能性があるなら、コピペでもいいのでコミットメッセージに情報を残すことも考えてみてください。
ファイル内のコメントについて
プログラムソースなど、ファイル内にコメントを残すことができる場合はここに書いたような情報をコメントとして関連個所に書き添えておいたほうがいい場合があります。特に、一見して不自然な状態となってしまう場合はコメントが必要とも言えます。コミットメッセージを書く過程で気付くこともあるので選択肢として考えておいてください。
コメントが使えないバイナリファイルなどで同様に情報を残しておきたい場合は、対象ファイルの隣に「～について.txt」のようなファイルを置くことも考えられます。
整合性を保つようにコミットの単位を考える
複数に分けると整合性が崩れる（エラーが発生したり、文書間で矛盾が発生する）ような変更はなるべく一度のコミットで済ませてください。
分けられたコミットとコミットの間には時間が発生するので、その間の整合性が崩れた状態を誰かが取得してしまうかもしれません。また、バグの調査などでバージョンを戻す場合にも整合性が崩れているコミットがあると邪魔になります。
整合性を崩すようにコミットの単位を分けると、多くの場合はコミットメッセージに似たような内容を書くことになります。そんなことになりそうな時は一度にコミットしてしまうことを考えてください。
一時的に整合性が崩れる変更を行いたい場合は専用のブランチを作るなどで問題を回避・軽減できる可能性はあります。
複数の変更はなるべく別々にコミットする
コミットメッセージに書く内容としてあまり関係ない複数の変更が挙がったときは、それらを別々のコミットとすることができないか考えてください。
複数の独立した変更を同時にコミットしてしまうと、変更内容のレビューや、それらの変更のうちのどれかを元に戻すなどの操作が難しくなってしまいます。