変更履歴を、もっと前のバージョンが現在のバージョンとどう違うかを説明する、 概念な“復元一覧表”として考えることができる。人々は現在のバージョンを見 ることができる。彼らは何がその中にあるのかを言うのに変更履歴を必要としな い。変更履歴から欲しいものはもっと前のバージョンがどう違ったのかに関する、 すっきりした説明だ。
変更履歴ファイルは通常ChangeLogと呼ばれ、ディレクトリ全体を包含す る。それぞれのディレクトリはそれ自身の変更履歴を持って良いし、あるディレ クトリはその親ディレクトリの変更履歴を使って良い。—それはあなたに任さ れる。
他のやり方は変更履歴をRCSやCVSのようなバージョン管理システムで記録するこ とだ。これは自動的にChangeLogファイルに変換される。
変更の目的全部やそれらが一緒にどう働くのかを記述する必要性はない。もし変 更が説明を必要とすると考えるなら、おそらくその通りだ。それを説明してくだ さい。—しかしコードのコメントに説明を入れてください。そこは人々がその コードを見るときはいつでも見るところだろう。例えば、関数を加えるとき、 “New function”は変更履歴には十分だ。なぜなら、それが何をするのか説明す るために、関数定義の前にコメントがあるはずだからだ。
しかしながら、ときどき変更の組の全体の目的を記述する一行を書くのが有用だ。
ChangeLogに項目を加える一番簡単な方法はEmacsのコマンド、M-x add-change-log-entryを使うことだ。項目はアスタリスク、変更されたファイ ルの名前、そして変更された関数、変数、それ以外のものの名前を丸括弧の中に 含むべきだ。その後にコロンを付ける。そしてその関数や変数に行った変更を記 述しなさい。