YamaKen
yamak****@bp*****
2005年 10月 8日 (土) 05:38:28 JST
ヤマケンです。反応が遅くなってすいません。 At Thu, 15 Sep 2005 07:40:43 +0900, tkng****@xem***** wrote: > お待たせしました。コミットポリシー原案です。あまりまとまってませんが、こ > れを叩き台としてコミットポリシーを確定したいと思います。あくまでコミット > ポリシーですので、コーディングスタイルなどに関しては触れていません。スタ > イルもぼちぼちと統一していきたいところですが、これはまた後ほど。（私は > コーディングスタイルには大して意見は無いので、誰かが発案してくれると嬉し > いです。） ありがとうございます。コピペコーディングや不適切なタイミング・手 順によるインタフェイスの変更を防ぐためのルールも必要ですが、それ は別途議論しましょう。 また、長々とした文章では何をどうすべきかはっきりしませんので、最 終的な規約では守るべきルールとなぜそうすべきかを以下のように1ルー ル毎に箇条書でまとめましょう。これは例なので正式版は別途策定する 必要あります。 ・どの関数を触ったかlogに残す 論理の変更(リファクタリングも含む)を行った関数については、最低 でも関数名をcommit logに残す。その関数に関心のある人が変更を確 認したり、後からデバッグする際に問題のありそうなrevisionを確認 するのを可能にするため。見た目の変更は無理に関数名毎の記録を残 さなくても問題ない。 ・commit前にdiffを一通り頭から眺める 論理も軽く再確認するのが望ましいが、ざっと流し読みするだけでも、 意図していないおかしな変化を検出できる(おかしなfile property、 行末のwhitespace付加等)。 > □コミットする単位に関して > > コミットするのは一まとまりの単位毎にしましょう。何をもって一まとまりとす > るか、というのは難しい問題ですが、現状では、複数の機能改善等が一度にコ > ミットされるケースが散見されます。これは以下の点で問題です。 > > ・revertしにくい > ・コードを読んで把握しにくい > > コミット単位が小さくすると今度は動かないrevisionが出てくるよ問題が発生す > るものと思われますが、とりあえずは現状を改善するために、コミット単位は小 > さくしていきましょう。合言葉は「迷ったらこまめにコミット」で。 > > 特に、バグフィックスと機能追加はできるだけ混ぜないようにしましょう。同じ > 箇所に対する変更であっても、一端バグを修正して、それから機能を追加するよ > うにしましょう。これは、バグ修正を安定版ブランチへ適用する事が目的です。 > （ただし、「書き換えたらバグがなくなってしまった」というような場合は除き > ます。このような場合は、深刻なバグであれば、別途0.4ブランチで修正するし > かないでしょう。） 賛成です。規約自体は上述のように箇条書にしましょう。 > □コミットの種類に関して > > コミットによりリポジトリに加えられる変更には、さまざまなものがあります > が、ここではおおざっぱに以下のようにわけてみます。 > > (a)バグ修正 > (b)機能改善（小） > (c)機能改善（大） > > バグ修正は字面の通り、バグ修正です。機能追加（小）は、小さいコードの変更 > 量で新しい機能を追加したり、既存の機能を改善したりするものです。目安とし > てはdiffが30行以内、ぐらいを想定しています。このような分類を作った目的 > は、「この変更はどのブランチにコミットするべきか？」というのを簡便に判定 > することです。 30行以内(unified diffですよね?)では本当に些細な修正しかできない ので実態に合わないと思いますが、変更の大きさに客観的基準を設ける 事には賛成です。 > trunk:通常は制限なし。リリース三日前ぐらいからはcは行わない。0.6が近付 > いたら状況は変わるかも。 本来ならcode freezeと共にそのバージョン専用のリリースブランチを 作成してtrunkは自由にしておくべきだと思いますが、とりあえずは了 解です。 > 0.4: a, bのみ。bを行うかどうかは各コミッタで判断。bの判断規準は「迷った > らコミットするな。」逆に、trunkにコミットしたバグ修正は、問題なく適用で > きる限り0.4にもコミットすること。 了解です。ただし、API/ABIの変更があった場合にはdoc/COMPATIBILITY に記述する事にしましょう。また、ABIの変更(例: r1309)は原則として 避けるべきです。たとえそのAPIが使われてなかったとしても。 > r5rs:制限なし。trunkへのマージが近付いたらしばらくはバグ修正とtrunkから > の同期作業のみ。マージ時期に関しては別途告知を出すこと。 了解です。 > □trunkとr5rsの同期に関して > > r5rsブランチでsvk pullを行うと、自動でtrunkでの変更をr5rsブランチに追 > 加してくれます。というわけで、基本的には手作業でr5rsブランチにtrunkでの > コミットを適用する必要はありません。1週間に1度、もしくはそれ以上の頻度を > 目安にマージを行うこと。 完全に自動的には同期できない事を前提に続けましょう。 > □ファイルの追加に関して > > ファイルを追加した場合、Makefile.amに適切な記述を追加することを忘れる > と、ビルドできなかったり、動かない原因になります。単純な場合に関しては > make releasetestによるテストで回避できますが、以下の場合に関しては特に気 > を付けて回避しなければなりません。 > > ・Schemeのファイルを追加した場合 > ・デフォルトでconfigureオプションがオフの場合 > > 前者はSchemeのテストコードを追加する事で回避できるでしょう。 > > 後者はmake releasetestのルールを変更しないと回避できません。configure > オプションを追加した場合は、make releasetestをいじる必要がないかどうか、 > 確認しましょう。 チェック項目を作成しましょう。ファイル追加時の整合性はできればス クリプトで自動チェックしたいですね。 > □テストに関して > > テストに関してはいろいろ改善したいところがあるのですが、とりあえず将来 > 的には「コミット前に関連テストにパスすることを確認すること」というポリ > シーを入れたい、というのが希望です。 commit毎に必ずテストというのはコストが非現実的なので受け入れ難い です。連続した5回のcommitで1つの目的を達成する場合もあるわけで、 そのような場合には最後にテストすればOKでしょう。もちろんサッと終 わる自動テストが対象コードに用意されてるならそれを走らせるぐらい は推奨していいでしょうが。 あまりキツいルールを課すとかえって守られなくなります。 > □コミット前の作業に関して > > svn diffで、コミット前に変更点をもう一度確認しましょう。 上述のように、なぜそうすべきか明示しましょう。 ・commit前にdiffを一通り頭から眺める 論理も軽く再確認するのが望ましいが、ざっと流し読みするだけでも、 意図していないおかしな変化を検出できる(おかしなfile property、 行末のwhitespace付加等)。 > □コミットログに関して > > コミットログにはそのコミットの目的を書きましょう。目的が書けないような > コミットは行うべきではありません。もしくは、目的の分類が不十分です。目的 > は以下のようなものに分類されます。（ここに無いものがあれば追加してくださ > い。） > > cosmetic change, bug fix, new feature, refactoring documentationを追加しましょう。あと"bug fix"は複合語として "bugfix"にした方が扱いやすいように思います。好みですが。 それから、[*new feature*]のような形式で重要性を示すのはどうでしょ う? 前回リリースからの差を確認したり、少ない時間で開発を追うのに 便利だと思います。ChangeLog生成時にはこの重要な変更のみを含める ようにした方がいいかもしれません。 あと外部からパッチをもらった場合にChangeLogに本人の名前を残せる ように定型文で言及するようにしましょう。 [new feature] Patch by HOGE Fugao <hoge****@examp*****> posted in [Anthy-dev 65535]. These functions ... ↓ 2005-10-08 HOGE Fugao <hoge****@examp*****> [new feature] by the patch posted in [Anthy-dev 65535]. These functions ... > コメントやドキュメントの変更はどうしようか迷い中。以下のような感じで書 > くことを想定しています。ログの書式は以下のような感じで考えてます。 > > [bug fix] Fixed a typo. > * uim/uim.c: > -(uim_init): Replaced 'uiim' with 'uim'. いくつか変えたい点があります。 ・commitのカテゴリ(と要約)の後には空行を挿入すべき ・変更内容が自明な場合("[bug fix] Fixed a typo")は要約は積極的に 省略し、単に"[bug fix]"とした方がよい また、uimのcommit logはある程度ChangeLog形式に似せてあるのでその 慣習に従って以下のようにすべきと思います。 ・"replaced"のように無理に時制を合わせようとせず、単に"replace" とする ・"uim.c: (uim-init):"のように関数名等がリストされている場合はファ イル名の直後にはコロンを付けず"uim.c (uim-init):"とする http://www.gnu.org/prep/standards/standards.html#Style-of-Change-Logs テキスト整形ルールについては以下の3つが候補になるかと思います。 徳永さんの形式はChangeLogとしても一般的なitemized listとしても中 途半端なので見る人にメリットが無いと思います。 私は3番目のitemized形式が見やすいと思いますが、意見が割れるよう なら標準であるという事で1番目のChangeLog風にしましょう。 font-lockすればまあそれなりに見れますし。 ほぼChangeLog風: ---------------------------------------------------------------- [bugfix] This explanation is explanation for explanation so don't mind this. * uim/uim.c (uim_init, uim_create_context, get_context_id) (uim_reset_context): Fix a typo 'uiim' with 'uim'. (uim_quit): Fix incorrect function definition. This explanation is explanation for explanation so don't mind this. ---------------------------------------------------------------- indented: ---------------------------------------------------------------- [bugfix] This explanation is explanation for explanation so don't mind this. * uim/uim.c (uim_init, uim_create_context, get_context_id, uim_reset_context): Fix a typo 'uiim' with 'uim'. (uim_quit): Fix incorrect function definition. This explanation is explanation for explanation so don't mind this. ---------------------------------------------------------------- itemized: ---------------------------------------------------------------- [bugfix] This explanation is explanation for explanation so don't mind this. * uim/uim.c - (uim_init, uim_create_context, get_context_id, uim_reset_context): Fix a typo 'uiim' with 'uim'. - (uim_quit): Fix incorrect function definition. This explanation is explanation for explanation so don't mind this. ---------------------------------------------------------------- ------------------------------- ヤマケン yamak****@bp*****
