パッケージの説明など,ユーザがパッケージを入手した際に最初に目にするファイル.

ユーザ向けのパッケージの変更記録.決められた形式はないが,最新版に対するニュースを頭に書く.ユーザ向けなので,当然ユーザに見える機能についての記述となる.大抵はバージョン番号による見出しとそのバージョンに対する変更という組合せの繰り返しのようだ.例.

バージョン 2.0
* aaa
* bbb

バージョン 1.0
* ccc
* ddd

GNU コーディング規約によると,NEWSファイルが長くなった場合は古いNEWSはONEWSファイルを作成して,NEWSファイルの最後でそれを参照するように書くとよいらしい.

そのパッケージの開発者の名簿.特に決まった形式はないようだ.開発者に連絡できるようにメールアドレスなどが書いてあることもある.さらにそのパッケージのどの機能に携わったのかといった情報が書いてある場合もある.開発者がそのパッケージにかかわったということを記録に残し,アピールできる場でもある.

開発者向け変更履歴.GNU コーディング規約において詳しい記述がある.以下要点.

目的

バグ発生箇所の追跡.プログラムの方針の食い違い発生の防止.

考え方

現バージョンと以前のバージョンの違いに関する説明を記述する.

ファイル名

ChangeLog

記述範囲

ChangeLogファイルが置かれているディレクトリ全体をカバー.サブディレクトリがある場合は各ディレクトリ毎に書くのもアリ.

記述内容

詳細な記述はソースのコメントに記述し,ChangeLogにはそれを参照するトリガーとなる記述があればよい.つまり変更の目的などの詳細情報は必要ない.ただし,変更量が多い時には変更の概要を記述が役立つこともある.

記述形式

セマンティクス

日付 名前 <メールアドレス>

* ファイル名 (関数名のリスト): 変更の説明
(関数名のリスト): 変更の説明
* ファイル名 (関数名のリスト): 変更の説明

* ファイル名 (関数名のリスト): 変更の説明
(関数名のリスト): 変更の説明

* ファイル名 (長い関数名のリスト1)
(長い関数名のリスト2): 変更の説明

記述形式に関する注意

• 関数名や変数名は略さない.完全な形で記述する(正規表現などもしない).
• 関連のない項目(*で始まる行)は空白で区切る.上の例では最初の二つの*で始まる項目と三つめの*で始まる項目は関連がない.
• 連続した項目が同じファイルなら*とファイル名は省略できる.
• 関数名のリストが長い場合は,','ではなく')'で閉じて分割し,継続行は'('で始める.

ありがたいことにChangeLogの作成を支援してくれるツールがいくつかある.

EmacsのChange Log mode

Emacsでソースに変更を加えた後,そのファイルのバッファにカーソルがある状態でM-x add-change-log-entryとすると,変更履歴ファイル名を聞いてくるので,それに答えると

日付  現在のユーザ名  <メールアドレス>

	* それまで開いていたファイル名: 

と記述してくれる.さらに新しい変更点が上にくるように*で始まる項目を適切な位置(実行した日付の一番上)にセッティングしてくれる.

rcs2log

RCSもしくはCVSの作業ディレクトリで

$ rcs2log [オプション] [ファイル名]

とすると標準出力にChangeLog形式の変更履歴を作成してくれる.リポジトリに登録されているファイルを指定すればそのファイルに対する変更履歴を作成してくれる.*で始まる項目commit単位のようだ.:以降の説明にはcommit時に記述した内容が記述される.