RepoCommit

開発に参加したい方へ＞[Subversion]＞リポジトリガイドライン＞Commit

Commit

2006.03.25 Commit手順の検討メモ にて検討を加えて書き直しました．

正式branchへのCommit手順

ファイルに変更を加えたときには必ず別の人のReview processを経ること．(ただし，更新履歴についてはこの限りでない)

変更→パッチ作成→レビュー→(必要に応じて作業ブランチを作成)→問題がなければtrunkへ

trunkへのレビュー前のCommitは禁止する．変更した人はCommit前にパッチを公開してレビューを求め，問題がないことが確認されたら trunkへCommitする．変更が軽微ではなく十分にバグフィックスが行えないと予想される場合，あるパッチを前提としたのパッチ(機能追加や他の人からのパッチ)が出るような状況，には一時的な作業ブランチを作成してそこで作業を行う物とする．

基本手順を以下で説明する．

ファイルの変更

Checkoutした作業領域でファイルの編集を行う．

Commit権限がない場合には機能の実装あるいはバグ修正が完了したら開発者掲示板にて差分ファイルの提供を行う．

パッチの標準形式は unified diffとするが，リビジョンを明確にした変更ファイル一式でもよい．TortoiseSVNを利用している場合には，TortoiseSVNの「Create Patch...」を使うことを推奨する(他の人が容易に適用できるので)．差分提供時には変更元となるバージョン/リビジョン番号を明確に伝えること．

[例] sakura/trunk#945 : sakura/trunk がブランチ， #945がリビジョン

Create Patchを使った場合には差分ファイルに元のバージョンが組み込まれて適用時にそれが考慮されるので，掲示板やコメントへのリビジョンの記入は必須ではない．しかし，どのようなツールを使うかは不定という前提の元で一応記入するきまりとしておく．

変更箇所には必ず変更理由，日付，変更者をコメントとして記入すること．

パッチの公開場所

• SourceForgeのPatches (パッチの状態管理が出来る．おすすめ．ただし，添付ファイルの登録には開発者登録が必要．)
• 各自のホームページスペース : ただし，長期間にわたって保持されることが前提．
  保存期間の短いアップローダは使わないこと．

パッチのレビュー

パッチを公開したら別の人のレビューを待つ．不完全であってもそれを明らかにして公開するのはかまわない．ただし，不完全なパッチにはコメントが付きにくい傾向にある．公開時には変更点の概略，動作確認済みの手順が添えられていることが望ましい．

レビューの完了は適宜掲示板での返信を目安に判断することにする．

主な確認ポイント：

• 機能が実用上完全であるか．
• 操作性に優れているか
• ソースコード記述が冗長でないか
• 関数の位置が適切か，メソッド名が適切か．
• メモリ管理が正しく行われているか
• コメントで変更者・変更点が明らかになっているか
• 関数のコメントが適切か
• 正確に動作するか
• レビューと並行してテスト版バイナリを用いたテストを進めるのも有効である．これについては各人の判断に任せる．

例外：コメントのみの修正の場合には最初からパッチを作成することなくtrunkへCommitしてもかまわない．但し，コンパイルエラーが出ないことを事前に確認すること．(修正ミスを防ぐため)

Private Branchへの登録

次のような理由により，パッチのままでは管理が難しい場合には一時的なPrivate Branchを作成してリポジトリに登録する．

• １つの機能を複数人で開発する．あるパッチの修正パッチが別の人から出される．
• あるパッチの存在を前提としたパッチが作成される場合の，その前提となるパッチ．
• 機能・実装が複雑，あるいは他の機能への影響が大きく，ソースのトレースや一部の人のテストでは十分に検証できないと思われる場合．

Private Branchでの確認が不要なケース

• 変更箇所が1関数内
• ヘッダファイルの定義追加
• 特定のコマンドの処理のみに関係する
• コメントのみの修正

Private Branchでの確認が必要となるケース

• 変更が複数のソースファイルにまたがっていて，しかもそれぞれが異なる変更で連携している．
• 正規表現に関する変更．
• 文字編集，文字列保存など基本機能の変更，修正．
• クラス構造の大幅な変更

Private Branchへは機能的に不完全なものや検証が完了していない物も登録してよい．パッチ提供者がCommit権限を持っていない場合には権限を持つ人が代理で行う．

Repository 登録 (Commit)

レビューにより十分に問題が取り除かれたら，Commit権限のある人がそれをリポジトリのtrunkへ登録する．登録が完了したらブランチ名とリビジョンを掲示板の議論に対する返答の形で公開する．

Commit時は原則としてレビューが完了していなくてはならないが，実際問題として機能追加が大きく，その内容が複雑あるいは高度な場合など適切なReviewerが見つからない場合も考えられる．そのような場合はテスト版での評価が十分に行われれば Commit可能とする．(実際そこまで複雑な変更が加えられた場合に実際の動作確認無しでCommitするのは危険であろう．)

Commit の基本的注意

trunk/Privateを問わず，Commit操作を行う場合には以下に述べる点に注意すること

１つの変更は1回で行う

SubversionではAtomicな操作はAtomicとして扱うため，2つの変更ファイルがあった場合に同時にCommitするとリビジョンが１つだけ上がるのに対し，それぞれをCommitするとリビジョンが２つ上がる．後者ではリビジョンが無駄に消費されることもさることながら，1つ前のリビジョンとの差を取った場合に完全な変更イメージを取り出せないという問題がある．

１つのまとまった変更に対するCommitは必ず1回で操作すること．その際１つのリビジョンに対して１つのMessageが付くようにする．

1 つずつCommitする

これまでとは正反対の考え方となるが，複数の変更をまとめずに別々にcommitする．それぞれが関連しあっていてtrunkで行うには数が多い場合にはPrivate Branchを作成して作業を行う．(このような場合には全てをまとめたとしてもtrunkにいきなりcommitするには大きくなりすぎるために Private Branchを作らざるを得ないと思われる)

Commit メッセージの書き方

Messageの前に変更の種別が容易にわかるように接頭辞を付けることを推奨する．

Add: 機能追加， Imp: 機能改善，Fix: バグ修正， Chg: 仕様変更

日付，変更者などCommit時に自動的に記録される物は記入しないこと．但し，パッチ作成者がComitした人と異なる場合にはパッチ作成者への謝辞を記入してもよい．

[例]
Imp: ツールバーを浮動可能に (by ほろんさん)
Fix: ツールバーアイコンがへこんだまま戻らなくなる
Advised by はららさん

名前，内容は架空の物です．

コメントの日本語

今のところコメントは大部分が英語で記入されている．これはCVSが日本語を正しく扱えない可能性を考えて2バイト文字の使用を避けた結果であるが， SubversionではコメントをUTF-8で管理するので記入した2バイト文字が文字化けすることはない．しかし，ソースコード中の文字コードがShift-JISであるので， ViewVCにおいて両者が1画面に同時に表示されるケースで文字化けが発生する．そのような場合，現在のViewVCでは文字化け無く表示する方法はなく，view画面ではコメントの方が優先されてしまう．

しかし，downloadを選択してソースコードのみを表示させるか，あるいはブラウザでEncodeを明示的に選択することで文字化けを回避することができるので，内容が確認できないことはない．(ただしdownloadを選択した場合には色分け表示機能は使えない) また，差分表示においてはコメントは表示されないので文字化けは発生しない．

以上のことから，ViewVCの一部の画面においては多少の不具合があるが，コメントの有効性を最大限に使うためにもコメントに2バイト文字を使用できるものとする．使用言語は日本語または英語とする．

ファイルの追加

ファイルの追加はコード量や機能単位を勘案して各自の判断で行って良い．新規ファイルは作成時に以下のを付与すること．

• svn:mime-types
  • 2バイト文字が入ることのないテキストファイルの場合は text/plain
  • 2バイト文字が入るテキストファイルtext/plain;charset=SHIFT_JIS
  • 画像ファイルは適切なMIME type (image/*)
• svn:eol-style
  • native

新規ファイル作成時にファイル名に応じて自動的にプロパティが設定されるように，初期設定しておくことを強く推奨する．

ファイル中で使用する漢字コードはSHIFT JISとする．(EUC_JP, iso-2022-jp，UTF-8, Unicode等を使わないこと)

Private 領域へのファイル追加

開発対象そのものに必要なファイルを追加することは上に述べたとおり各自の判断で行ってよい．それ以外に開発ドキュメント，設計文書なども各自の作業エリアに新規ブランチを作成してテキスト，HTML文書及びそれに付随する図表等を追加してもよい．

次のような物はリポジトリに登録してはならない．

• 他人の著作物の複製 (一部に含む場合も同じ)
• 開発対象と無関係なソフトウェア．文書
• 開発対象をコンパイルして出来たバイナリファイル
• コンパイラの副生成物: オブジェクトファイル (.obj)，Incremental linker (.ilk)，プリコンパイルヘッダ (*.pch)等

バイナリファイルや中間生成物の誤登録を防ぐため，中間生成物の作られる可能性のあるディレクトリには予めsvn:ignore属性を付け，誤操作によってもCommit出来ないようにしておくこと．

ファイル名の変更

ファイル名の変更，ディレクトリ構成の変更は掲示板での議論の結論を待った上でtrunkブランチに対して行う．(基本的には行わない)