この文書はソフトウェア開発活動でSubversionを最大限に利用するための すぐに使えるガイドライン集です。(この文書について)
リポジトリのレイアウトには多くの流儀があります。 Subversion においてはブランチやタグは普通のディレクトリですので、 ブランチやタグをリポジトリ構造の中で意味付けしてやる必要があります。
Subversion プロジェクトは「プロジェクトルート」という考え方を公式に お勧めします。「プロジェクトルート」はリポジトリにおいてプロジェクトを 指し示す固定された場所です。一つの「プロジェクトルート」には、 /trunk, /branches, /tagsの 3つの子ディレクトリのみを置きます。 単一のリポジトリには単一の プロジェクトだけを置いてもよければ、単一のリポジトリに多数の プロジェクトを置いても構いません
参考文献: Choosing a Repository Layout.
(これの古いバージョン(For Subversion 1.2)に対する日本語訳:リポジトリレイアウトの選択。)
(訳註: このセクションについては内容にほとんど変化がないため古いバージョン
向けでも問題ないと思いますが、この日本語訳全般は古すぎるバージョンに
対するものですので全くお勧めできません)
変更をコミットする際、その変更は単一の目的を達成するためのものにしましょう。 特定単一の不具合の修正、単一のフィーチャーあるいは個別のタスクの追加など。 コミットによって作られる新たなリビジョン番号は永劫にその変更に対する「名前」 として使用できます。このリビジョン番号はバグデータベースでこの変更に 言及するののに使用したり、変更を取り消すためあるいは他のブランチへと 変更を採り入れるためにsvn mergeの引数として使用したりできます。
参考文献: Changesets.
(訳註: 古い日本語訳(For Subversion 1.2)には対応する項がありません。
オライリー・ジャパンによる出版「実用Subversion 第2版」
(Subversion 1.5に対応)にはあるようです)
なるべく多く、Subversionの変更の集合(changesets)と問題追跡データベース (issue-tracking database)との間の双方向のリンクを作るようにしましょう:
### このお勧めは時代遅れです ###
(訳註: Subversion 1.5 (2008年6月)にて svn:mergeinfo 属性が自動で
付与されるようになったため、このセクションのようなことは不要になりました)
マージの成果をコミットする際、必ず何をマージしたかの説明となっている ようなログメッセージにしましょう。例えば:
Merged revisions 3490:4120 of /branches/foobranch to /trunk.
和文の場合:
/branches/foobranch の 3490:4120 を /trunk へマージ。
参考文献: Tracking merges manually, および Merging a whole branch to another。 (訳註: どちらも Subversion 1.0向けの文書であることに注意)
作業コピーのディレクトリ群やファイル群はばらばらな「ワーキング」 ("working")リビジョンからなっていることもあります: これは古いバージョンの ものと新しいバージョンのものを組み合わせることを可能にするための 意図的なものです。それでも、ほんのちょっとだけ知っておくべき事柄があります:
参考文献: Mixed-revision working copies. (これの古いバージョン(For Subversion 1.2)に対する日本語訳:混合リビジョン状態の作業コピー。)
Subversionの優れた特長として、設計からして扱えるファイルのサイズの 上限は ありません。ファイルはクライアントとサーバーの間の双方向で 「ストリーム」として 送られ、その際にネットワークの両側で使用する メモリの量は小さく、かつ一定です。
もちろん、実用上考えなければならない問題はいくつもあります。 キロバイト単位の大きさのファイル群(例えば、典型的ソースコードファイル等)を 扱うのには何の心配もないのに対して、より大きなファイル群をコミットするには とんでもない量の時間と空間の両方が必要になることもあります(例えば、 数十、数百ものメガバイト単位のファイル群等の場合に)。
はじめに、Subversionの作業コピーはバージョンコントロール下にある すべてのファイルのコピーを無修正の状態で.svn/text-base/ (訳註: Subversion 1.7以降では作業コピーのルートディレクトリの下の .svn/pristineの中に変更されています)に保持していることを 記憶に留めて下さい。これは、作業コピーには元のデータセットの最低でも 2倍のディスク空間が必要であるということです。 さらにSubversionのクライアントはファイルをコミットするのに以下の (現時点では調整のできない)アルゴリズムに従います(訳註: ここに 示されているのは Subversion 1.6 時点でのアルゴリズムです。 Subversion 1.7 ではwc(作業コピー)APIはWC-NGとして再実装されていますが、 この文書にはそれ以降の変更が反映されていないと思われます)。
そのようなわけで、ファイルの大きさについて理論上の制限がない一方で とても大きなファイルに対してはクライアントがのろのろと進んでいるのを 待つのにかなりの忍耐が必要になることを知っておく必要があります。 そのかわり、CVSとは違ってあなたの大きなファイルがサーバーに収容 できないことがないであろうこと、他のユーザーへと影響を与えたりしないことに ついては確実に安心して構いません。
これは活発に議論されている疑問であり、それはまた、全く以って ソフトウェアプロジェクトの文化に依存するものです。 ここでは単一の万能なポリシーを示すことはせず、広く使われている3つの ポリシーを述べます。
(まだ実行可能なコードが出来るところまで至っていない、生まれてまもない プロジェクトでしばしば使われます)
利点: ポリシーに従うのがとても簡単です。新規の開発者が 参加するのに障壁が小さいです。誰もブランチをどうやって作るか、 どうやってマージを行うのかを学ぶ必要がありません。
欠点: 混沌とした開発手法となり、いつ何時でもコードが 不安定になることがあります。
追記: この類の開発手法では Subversion は CVS よりもほんの少しだけ 危険性が小さいです。というのも、Subversion のコミットは不可分 (アトミック/atomic)(訳註)であるため、 他の誰かがコミットを行っている最中の「途中の」コミット結果をチェックアウトや 更新で受け取ることが決してありません。
(訳註 不可分(アトミック/atomic): 分解不能な(こと)。つまり途中の状態が存在しないこと。 この場合はコミット前の状態とコミット後の中間の状態が見えないこと
(手厚く管理・監督されているプロジェクトでしばしば使われます)
利点: /trunk はいついかなる時でも極度に安定している ことが保証されます。
欠点: コードを書く人は意図的に互いに分離されていますので、 必要以上にマージ時の衝突(conflict)を生じさせるかもしれません。 利用者に多大に余分なマージを強います。
(これはSubversionプロジェクトで使用しているシステムです。)
利点: /trunk はいついかなる時でも極度に安定している ことが保証されます。ブランチ作成/マージの煩わしさはある程度 稀なものになります。
欠点: 利用者の日々の作業にちょっとだけ負担を増します: 利用者は各コミットの前にコンパイルおよびテストをしなければ なりません。
この文書はApache Subversionの 配布物の中で doc/user/svn-best-practices.html として配布されている文書を ふたつきが個人的に日本語訳を 試みたものです。過去にもこの文書を日本語訳をされた方はいらっしゃるかも しれませんが、そうした訳は参考にせずに訳出しています。ただし、 "Version Control with Subversion"の 日本語訳(Subversion 1.2用)である「Subversion によるバージョン管理 For Subversion 1.2」 および、オライリー・ジャパンより出版された「実用Subversion 第2版」は訳語の確認等で読んではいます。
訳のベースとなっているリビジョンおよびタイムスタンプは r1837041 2018-07-30 10:25:24 +0000 (Mon, 30 Jul 2018) です。 将来的にはApache Subversionソフトウェア開発プロジェクトへと レビューを経て寄贈することになるかもしれませんが、その場合にはこのセクションは 削除します。
ライセンスについてはこのファイルの冒頭にHTMLのコメント要素として 埋め込んである定型の文言にある通りhttp://www.apache.org/licenses/LICENSE-2.0を御覧下さい。