2007-06-01
ChangeLog の作法 つづき
Subversion の開発者が ChangeLog について面白い記事を書いている. 記事の要旨はこうだ: ChangeLog (Subversion なので commit log) を書くのは面倒だよ, メーリングリストもあることだし書かなきゃダメ? ってよく訊かれる. 書きましょう. バグトラックもあるけど, 書きましょう.これらのツールは補完しあっている. メーリングリストはノイズが多いし, 変更を特定するには情報が足りない. バグトラックはバグの記録がメインだからコードの話を細々書くのは邪魔になる. 変更については ChangeLog に書くのがいい. プログラマは ChangeLog を読む. 記録を検索して, どの関数に何が起きたかを調べるものだ. この類の記録は ChangeLog を読まないとわからない. 逆に ChangeLog を書く時は, それを特定できるように省略せず名前を書くべきだ. 要旨ここまで.
先の記事で紹介されている "Hacker's Guide to Subversion" はログの書式の他も色々とよく書けている. このごろ commit が手抜きになっている私は反省した. そういえば, 以前 ChangeLog の作法 について書きかけたまま挫けている. 今日はその続きとしよう.
先の記事では ChangeLog をコード編集時のリファレンスと考えていた. たとえばある関数ついての変更を知るために ChangeLog を検索する. ここで検索を中心に使っている点に着目すると, ChangeLog は変更データベースのインデクスなのだと言える. キーは関数名などのシンボル. 件の検索も, 時間をかければ annotate と diff を駆使して絞りこんでいくことはできる. ただし時間がかる. だから ChangeLog を索引として準備したい. この主張はもっともだが, 一方でツールに頑張って欲しい気もする. チェックインに合わせて変更を解析し, 該当シンボルを commit log の雛形やプロパティに差し込む. 人間はその雛形に自然言語を追記する. そのくらいは頑張れないのかな. 誰か...
さて, 以前の私は ChangeLog を別の目的に使っていた. ChangeLog はコードレビュー会議のアジェンダだった. レビューはチェッイン後に行われ, レビュー会議ではレビューされる人が自分の作業を差分ごとに説明する. その説明に従ってレビュアはコードを眺める. 私はよくこの説明にもたついていた. 自分で加えた変更の詳細を忘れてしまい, 少し説明をしてから "あれ...ごめん違った" と手戻りすることが多かった. 時間を浪費するミーティングはなるべく短く済ませたい. そのための準備として ChangeLog を入念に書こうとした. なお, この方法は OSS 風のチェックイン前レビューにも使えると思う. patch を添付したメールの本文がこのアジェンダになる. いずれにせよレビュアの負担は少い方がいいからね.
記録置き場の力関係
...このあいだはこんな話を書こうと思っていた. でもいくつか考えごとをしているうちに記事のことを忘れてしまっていた. 考えごとの一つは先のようなツール支援の問題. 私も関数名を手書きするのはかったるいと思っていた. かったるい方法を主張したくない.
もう一つは, 前提となっている差分毎レビューへの疑問. レビューは自己完結した "機能" 単位で行う方がいい. コードと機能の整合性を確認しやすい. 一方で作業中はもう少し細かい単位でコミットしたい. レビュアとプログラマでは望ましいコミットの粒度が異る. 気楽にブランチできる SCM が欲しくなり, SVK などを物色していた.
その他にバグトラックとの兼ね合いも気にしていた. ChangeLog がレビュー会議のアジェンダだとしたら, 議事録はどうしよう. 当時は ChangeLog をコピーして議事録を追記していたけれど, 少し面倒だった. チームによっては議事からのタスクを全てバグトラックに入れているチームもあり, それも悪くなさそうに見えた. ただバグトラックを併用するとアジェンダと議事録(相当)の距離が離れてしまう嫌いはある. またレビューからの修正は細かなものも多く, バグトラックに書くのはなんとなく大袈裟な気がしていた. Trac のように ChangeLog と議事録(Wiki)とバグトラックが統合された仕組みを使えば こうしたバランスも変わるかもしれない.
SCM とバグトラックの共存を選ぶ Subversion に対し, Mozilla はバグトラック(Bugzilla)を中心に据えている. レビューの議論はバグトラック上で, ページ添付の patch を中心に進む. (メールもあるのかな.) ChangeLog はバグ ID を参照するだけの簡素なものだ. ソースコードから距離があるのは不便そうだが, 一方で Bugzilla は ChangeLog よりずっと高機能で, 構造化されている. しかし検索や操作の反応が遅いぶん, 索引として使うには弱い.
プロジェクトの規模も関係している気がする. Subversion と Mozilla ではコード量が一桁ちがう. 数十万行のコードなら ChangeLog とメールを活用する方が軽量でいいけれど, 数百万行になるとそれでは破綻するのかもしれない.
こうしたことをふらふら考えていたが, 結論はなかった. といいつつまとめ:
- ChangeLog には二つの使い道がある
- 変更のインデクス, コードレビューのアジェンダ
- 変更の記録媒体ははプロセスや規模によって使いわけたい
- 気楽なメーリングリスト, 構造化されたバグトラック, コードに近い ChangeLog