Subversion (SVN) は、Git に似たバージョン管理システムです。コマンドラインでも使えますし、Tortoise SVNなどの GUI アプリケーションでも使えます。SVN を初めて使う場合は、SVN クライアントの比較を見てから、どれが最適かを決めることをおすすめします。
このドキュメントは、SVN を使用するための完全で堅牢な説明 ではなく、WordPress.org でプラグインを始めるための簡単な入門書です。より包括的なドキュメントは The SVN Book を参照してください。
ここでは、WordPress.org ホスティングに関連する SVN の使用に関する基本的なことを説明します。SVN、そしてほとんどすべてのコードリポジトリ・サービスの基本的なコンセプトは変わりません。
追加情報については、以下のドキュメントをご覧ください:
概要
あなたのファイルはすべて、私たちのサーバー上の svn リポジトリ に一元的に格納されます。このリポジトリから、誰でもあなたのプラグインファイルのコピーをローカルマシンに チェックアウト できますが、プラグイン作者であるあなただけが チェックイン する権限を持っています。つまり、あなたはローカルマシンでファイルに変更を加えたり、新しいファイルを追加したり、ファイルを削除したりでき、それらの変更を中央サーバーにアップロードして書き戻すことができます。このチェックイン作業によって、リポジトリ内のファイルや WordPress.org のプラグイン・ディレクトリに表示される情報が更新されます。
Subversion は、これらの変更点をすべて記録しているため、必要であれば後で古いバージョンや リビジョン に戻って見ることができます。個々のリビジョンを記憶するだけでなく、簡単に参照できるように、リポジトリの特定のリビジョンに tag を付けるよう、Subversion に指示できます。tag は、プラグインの異なるリリースのラベル付けに最適で、WordPress.org で正しいバージョンが表示され、ユーザーのために更新されることを保証する、完全にサポートされた唯一の方法です。
あなたのアカウント
SVN 用のアカウントは、プラグインを申請したときに使用したアカウントと同じユーザー名 (メールではありません) になります。これは WordPress のフォーラムでも使用するユーザー ID です。
大文字と小文字が重要 であることを忘れないでください。— あなたのユーザー名が JaneDoe なら、大文字の J と D を使わなければ SVN は失敗します。あなたの名前の大文字小文字は、あなたのプロフィールで確認できます。
パスワードをリセットする必要がある場合は、login.wordPress.org にアクセスしてください。
SVN フォルダー
すべての SVN リポジトリには、デフォルトで3つのディレクトリが作成されます。
/assets/
/tags/
/trunk/
- スクリーンショット、プラグイン・ヘッダー、プラグイン・アイコンには
assetsを使ってください。 - 開発作業は、
trunkに置きます。 - リリースは、
tagsに入れます。
/branches/ ディレクトリは、使用されなかったため、デフォルトでは作成されなくなりました。_
Trunk
/trunk/my-plugin/my-plugin.php のように、trunk のサブフォルダーに置かないでください。インクルードされたファイルにはサブフォルダーを使うことができます。
/trunk ディレクトリは、あなたのプラグインコードを置くべき場所です。trunk は、最新かつ最高のコードと言えますが、必ずしも最新の「安定」コードとは限りません。trunk は、開発版用のものです。できれば、trunk にあるコードは常に動作するコードであるべきですが、必ずしも「安定版」ではないので、時々バグがあるかもしれません。単純なプラグインの場合、trunk がそのコードの唯一のバージョンかもしれませんし、それはそれでかまいません。
開発作業を別の場所 (Git リポジトリなど) で行っている場合でも、SVN と簡単に比較できるように、trunk フォルダーを常に最新のコードにしておくことをおすすめします。
Tags
/tags ディレクトリは、プラグインのバージョンを置く場所です。ここのサブディレクトリには、プラグインのバージョン管理と同じバージョン番号を使用します。ユーザーに正しいコードを提供するために、tag フォルダーを使用し、適切なバージョン管理が重要です。
プラグインのバージョン1.0は /tags/1.0 に、バージョン1.1は /tags/1.1 に、といった具合です。
私たちは、意味論的ソフトウェア・バージョニングの使用を 強く 推奨します。
Assets
Assets にはスクリーンショット、ヘッダー画像、プラグイン・アイコンがあります。古いプラグインでは、/trunk ディレクトリにスクリーンショットファイルを置くものもありますが、これは推奨されません。すべての新規プラグインは、/assets にスクリーンショットを置くべきです。プラグイン本体と一緒に WordPress インストールにスクリーンショットを送信する必要がないため、プラグインのファイルサイズを小さく保つことができます。
Branches
/branches/ ディレクトリは、デフォルトでは作成されなくなりました。このセクションは非推奨であり、情報提供のみを目的としています。
/branches ディレクトリは、プラグインのブランチを保存する場所です。おそらく開発中のバージョンやテストコードなどです。
WordPress.org のシステムでは、branches ディレクトリは 一切 使用されません。branches ディレクトリは、開発者が必要に応じて使用するためのものです。デフォルトでは作成されなくなったので、もう必要ないので無視してかまいません。
ベスト・プラクティス
あなたのコードを他の開発者が最もアクセスしやすいものにするために、以下のプラクティスが最適と考えられます。
開発には SVN を使用しない
これは、しばしば混乱を招きます。GitHub とは異なり、SVN は開発システムではなく「リリース」システムです。小さな変更のたびにコミットしてプッシュする必要はありませんし、実際そうすることはシステムにとって有害です。SVN にコードをプッシュするたびに、SVN にあるすべてのバージョンの zip ファイルを すべて リビルドします。プラグインのアップデートが最大6時間表示されないことがあるのはこのためです。その代わり、準備ができたら一回だけプッシュしてください。
コード用に trunk フォルダーを使用しする
多くの人は trunk をプレースホルダとして使っています。trunk のファイル readme.txt を単純に更新して、すべてを tag フォルダーに入れることは可能ですが、そうすると、コードの変更点を比較するのが難しくなります。その代わりに、trunk にはあなたのコードの最新バージョンを、たとえそのバージョンがベータ版であっても、入れておくべきです。
リリースには常にタグを付ける
プラグインの安定タグとして trunk を使うことは可能ですが、この機能は実際にはサポートされていませんし、推奨もされていません。代わりに、リリースには適切なタグを付けて繰り返しリリースする必要があります。そうすることで、自動アップデータとの完全な互換性が保証され、あなたのコードに問題があった場合にロールバック可能になります。
trunk から tag を作成する
コードを tag フォルダーに直接プッシュするのではなく、trunk でコードを編集し、readme に安定版と一緒に記載し、trunk から新規 tag にコードを その後 コピーしてください。
こうすることで、変更を簡単に確認できるだけでなく、SVN は変更されたコードだけを更新するので、より小さなコミットを行うことになります。これは時間の節約になり、潜在的なエラー (間違った安定版タグに更新してしまい、悪いコードをユーザーにプッシュしてしまうなど) を減らすことができます。
tag フォルダーがしばらく存在しなくても心配しないでください。svn cp を使って trunk を tag にコピーし、同時に SVN にプッシュできます。
ローカルで操作しているのであれば、trunk の更新と tag の作成を一度に行うことができます。リポジトリのルートをチェックアウトし、/trunk のファイルを更新し、svn copy /trunk /tags/1.2.3 (バージョン番号は例) を実行し、一括でコミットします。SVN は差分にもとづくシステムであり、コピー操作に svn を使用する限り、履歴が保存され、他の人がフォローしやすくなります。
旧バージョンを削除する
SVN はリリース・リポジトリですので、多くの開発者は古い (サポートされていない) バージョンのプラグインを削除することを選択しました。2019年現在、ビルドプロセスは変更されたファイルを含む tag にのみ対処するため、これはもはやリリースのスピードアップにはなりません。
例
新規プラグインの開始
プラグインを開始するには、すでにあるファイルを新規の SVN リポジトリに追加する必要があります。
まず、あなたのマシン上に SVN リポジトリのコピーを置くローカルディレクトリを作成します:
mkdir my-local-dir
次に、ビルド済みリポジトリをチェックアウトします。
svn co https://plugins.svn.wordpress.org/your-plugin-name my-local-dir
> A my-local-dir/trunk
> A my-local-dir/branches
> A my-local-dir/tags
> Checked out revision 11325.
この例では、Subversion は中央の SVN リポジトリから、ローカルコピーにすべてのディレクトリを追加 (「A」は「add」) しています。
コードを追加するには、フォルダー my-local-dir に移動します:
cd my-local-dir
コマンドラインからコピー & ペーストコマンドを使うか、ドラッグ & ドロップで、リポジトリのローカルコピーの trunk/ ディレクトリに、ファイルを追加できます。あなたがやりやすい方法でかまいません。
/trunk/my-plugin/my-plugin.php のように、trunk のサブフォルダーに置かないでください。インクルードされたファイルにはサブフォルダーを使うことができます。
いったんファイルが trunk フォルダーに入ったら、それらの新しいファイルを中央リポジトリに加え戻したいことを Subversion に知らせる必要があります。
cd my-local-dir
svn add trunk/*
> A trunk/my-plugin.php
> A trunk/readme.txt
すべてのファイルを追加したら、中央リポジトリに変更をチェックインします。
svn ci -m 'Adding first version of my plugin'
> Adding trunk/my-plugin.php
> Adding trunk/readme.txt
> Transmitting file data .
> Committed revision 11326.
すべてのチェックインにコミットメッセージを含めることが義務付けられています。
「Access forbidden (アクセス禁止)」という理由でコミットが失敗し、あなたがコミットアクセス権を持っていることが 分かっている 場合は、チェックインコマンドにユーザー名とパスワードを追加してください。
svn ci -m 'Adding first version of my plugin' --username your_username --password your_password
ユーザー名は 大文字と小文字を区別する ということを忘れないでください。
既存ファイルの編集
プラグインをディレクトリに入れたら、どこかの時点でコードを編集する必要があるでしょう。
まず、リポジトリのローカルコピーに入り、最新の状態であることを確認してください。
cd my-local-dir/
svn up
> At revision 11326.
上記の例では、すべて最新の状態です。中央リポジトリに変更があった場合、それらはダウンロードされ、あなたのローカルコピーにマージされたでしょう。
あとは好きなエディターを使って、変更が必要なファイルを編集すれば良いでしょう。
SVN の GUI ツール (Subversion や Coda など) を使っていない場合でも、変更後にローカルコピーと中央リポジトリで何が違うかを確認できます。まずローカルコピーの状態を確認します:
svn stat
> M trunk/my-plugin.php
これは、ローカルの trunk/my-plugin.php が、中央リポジトリからダウンロードしたコピーとは異なる (「M」は「modified」) ことを示しています。
このファイルのどこが変わったのか見てみましょう。それをチェックして、きちんと表示されているか確認しましょう。
svn diff
> * What comes out is essentially the result of a
* standard `diff -u` between your local copy and the
* original copy you downloaded.
すべて問題がなさそうなら、変更を中央リポジトリにチェックインするときです。
svn ci -m "fancy new feature: now you can foo *and* bar at the same time"
> Sending trunk/my-plugin.php
> Transmitting file data .
> Committed revision 11327.
これで trunk のアップデートは完了です。
新バージョンへの「タグ付け」
プラグインを正式リリースする都度、そのリリースのコードのコピーに tag を付けるべきです。こうすることで、ユーザーは最新版 (または旧版) を簡単に入手でき、あなたは変更点をより簡単に追跡できます。また、WordPress.org プラグイン・ディレクトリは、どのバージョンのプラグインをダウンロードするように指示すべきかを知ることができます。
まず、コードを tags/ ディレクトリのサブディレクトリにコピーします。WordPress.org のプラグイン・ブラウザのために、新しいサブディレクトリは常にバージョン番号のように見えるようにします。2.0.1.3 が良いでしょう。Cool hotness tag は bad です。
SVN の機能を利用するために、通常の cp の代わりに svn cp を使用したいと考えています。
svn cp trunk tags/2.0
> A tags/2.0
いつものように、変更点をチェックしましょう。
svn ci -m "tagging version 2.0"
> Adding tags/2.0
> Adding tags/2.0/my-plugin.php
> Adding tags/2.0/readme.txt
> Committed revision 11328.
新バージョンに tag を付けるときは、trunk/readme.txt の Stable Tag フィールドを新バージョンに 忘れずに更新 してください。
おめでとう ! あなたはコードを更新しました !
備考
あなたのプラグインを使うすべての人に配布する意思と準備がないものは SVN に置かないでください。これには、ベンダーファイルや .gitignore など、あらゆるものが 含まれます。
また、zip ファイルをアップロードしては、いけません。ほとんどのコードリポジトリ・システムがそうであるように、SVN は個々のファイルをアップロードすることを想定しています。