モデルプロジェクト CVS ログ書法の手引き

概要

以下は dcmodel 群での CVS 管理におけるログメッセージの 書法について記すものである.

書法

インデント・リストのマーク

• RD の list の形式で記述する
  • 説明
    • 項目の前に必ず "*" をつけ, 空白を 1 つ空けてから記述する.
    • 改行する時はその次の行は 前の行の文字を書き始めたところ から記述する.
    • その項目についてより詳細な情報を記述する際には上記の行から さらに 2 つ分空白でインデントして "*" から始める. 上記 2 つの ルールは継承する.

  • 具体例

    # 例 (この行は書かないこと)
    
    * オリジナルの RD の書式に関しては, るびきちさんの RD 事始め,
      URL : http://www.rubyist.net/~rubikitch/computer/rd-intro/ を
      参照してください.
    * item 1
    * item 2
      * item 2-1
        * item 2-2
        * 小項目であっても, 改行は
          OK です.
          * item 2-3

言語

• 英語のログは必須 (大変な場合は簡単に, で良いのでとりあえずつける)
• 日本語のログも必須
  • dcmodel 関係者には, 日本人も多いと思われるため, 日本語のログも必須でつける.
• 英語・日本語を混ぜたログの書き方
  • 以下のように英語と日本語の間に空行を入れること.
    • 英語のログ, 及び日本語のログの各項目の間には, 原則として 空白を入れないこと. 万が一入れる場合には, それよりも多い行数 を英語と日本語の間に入れること

  • 具体例

    # 例 (この行は書かないこと)
    
    * English log1
    * English log2
      * Detail Description
    
    * 日本語のログ 1
    * 日本語のログ 2
      * 日本語のログの詳細情報

理由

一応, 上記のような書法にしようという理由を述べる.

見易さ

一度のコミットで必ず 1 つの修正ならばよいが, 複数の修正箇所が ある場合も多いと思う. そういった場合に, 上記のような箇条書き になっていると (おそらく) 読みやすいと思われる.

もちろん上記の方法に固定せずとも箇条書きは可能であるが, 機械処理や ログを並べてみたときのことを考え, そろえておく方が 望ましいと考える.

変換の容易さ

RD 形式にしておけば, いざ HTML や TeX などの形式への変更を考えた際, 既に解釈系が存在しているので (たぶん) 楽である.

英語

(どれぐらいの有用性があるか甚だ疑問ではあるが), 一応日本人以外のために 英語も記述しておく.

もちろん後々必要になってから加えるというのがまっとうな考え方であると 思うが, CVS ログメッセージは, CVS を利用して開発されるプログラムや ドキュメントと違い, 変更が (不可能ではないが) 非常に手間である. (無論 1 つならば簡単であるが プログラムの数 × コミット回数のログが できることになるのでとっても大変).

よって, 将来のことを半端に考え, 一応基本は英語とする. しかし, 悲しいかな (この文書の作者が正にそうであるが), 英語ではログに関する十分な表現が できない者もいる. またやっぱり日本人は日本語も見やすいため, 日本語のログも必須とする.