WordPress.org SVN公開手順｜初回デプロイ・assets・Stable tag設定まで

WordPress.orgのSVNは「配布用」——ここが最初に理解すべきポイント
ディレクトリ構成——assetsの配置場所だけは絶対に間違えないで
初回デプロイの手順
assets（バナー・アイコン・スクリーンショット）の設定
Stable tagとtagsの関係——リリースの仕組みを理解する
GitHubで開発してSVNで配布する——現実的なワークフロー
TortoiseSVN——Windowsで使えるGUIクライアント
1. よく使う操作
初回デプロイで踏みやすい落とし穴
commit前チェックリスト
参考リソース
まとめ

前編ではSVNの基本コマンドとGitとの違いを解説しました。この後編では、WordPress.orgへのプラグイン公開に絞って、実際の手順を解説します。

WordPressプラグインを公開して学んだSVNの使い方｜基本コマンドからブランチ運用まで

WordPress.orgプラグイン公開で必要なSVNの基本をGitユーザー向けに解説。checkout・commit・statusの使い方、trunk/branches/tagsの構成、ブランチ運用戦略まで実体験ベースでまとめました。

私がRapls PDF Image Creatorを初めてWordPress.orgに公開したとき、SVNのコマンド自体は前編の知識で足りました。でもWordPress.org特有の「お作法」——assetsの配置場所、Stable tagの仕組み、readme.txtとtagsの関係——ここでかなり手間取りました。

この記事では、その経験をもとに「最初のデプロイで知っておくべきこと」を中心にまとめています。SVNのコマンド操作は前編で学んだ前提で書いているので、まだ読んでいない方は先にそちらをどうぞ。

WordPress.orgのSVNは「配布用」——ここが最初に理解すべきポイント

WordPress.orgのSVNはGitHubのような開発用リポジトリではなく、完成したプラグインを配布するための専用リポジトリです。リリース単位でまとめてcommitするのがベストプラクティスです。

最初に伝えておきたいのが、WordPress.orgのSVNリポジトリの位置づけです。

GitHubのように「開発の過程をすべて記録する場所」ではありません。完成したプラグインを置いて、バージョンをタグ付けして、ユーザーがダウンロードできるようにする——それだけが目的の配布専用リポジトリです。

私は最初これを理解せずに、GitHubと同じ感覚で「ちょっと直した → commit」「README修正 → commit」と細かくcommitしていました。動作上は問題ないのですが、WordPress.orgの履歴が無意味なコミットで埋まってしまい、後から見返すと何がどのリリースに対応しているのかわかりにくくなりました。

リリース単位でまとめてcommitする。これがWordPress.org SVNのベストプラクティスです。

ディレクトリ構成——assetsの配置場所だけは絶対に間違えないで

最も多い間違いはバナーやアイコンをtrunk/assets/に置いてしまうことです。正しくはリポジトリ直下のassets/で、配置場所が違ってもエラーが出ないのが厄介です。

プラグインが審査を通過すると、以下のSVNリポジトリが自動で用意されます。

https://plugins.svn.wordpress.org/rapls-pdf-image-creator/
  trunk/      ← プラグインの最新コード
  tags/       ← リリース済みバージョンのスナップショット
  branches/   ← 開発用ブランチ（WordPress.orgではほぼ使わない）
  assets/     ← バナー・アイコン・スクリーンショット ★ここが重要

https://plugins.svn.wordpress.org/rapls-pdf-image-creator/

trunk/ ← プラグインの最新コード

tags/ ← リリース済みバージョンのスナップショット

branches/ ← 開発用ブランチ（WordPress.orgではほぼ使わない）

assets/ ← バナー・アイコン・スクリーンショット ★ここが重要

trunkはプラグインのコード本体を置く場所。ここが次のリリース候補です。

tagsはリリースの固定点。tags/1.0.0/のようにバージョンごとのディレクトリを作り、その時点のコードを保存します。WordPress.orgはこのtagsの中身をユーザーに配布します。

branchesはチーム開発用の分岐ですが、WordPress.orgのプラグイン公開では基本的に使いません。

assetsはプラグインページに表示されるバナーやアイコンの画像を置く場所です。

ここで最も多い間違いを先に書いておきます。

NG: trunk/assets/banner-772x250.png    ← これは間違い
OK: assets/banner-772x250.png          ← こちらが正しい

1 2	NG: trunk/assets/banner-772x250.png ← これは間違い OK: assets/banner-772x250.png ← こちらが正しい

画像ファイルはリポジトリ直下のassets/に置きます。trunk/の中ではありません。私もこれを間違えて、プラグインページにバナーが出ない → 何度commitしても反映されない → 半日悩む、という経験をしました。配置場所が違うだけで、エラーメッセージも出ないのがタチの悪いところです。

初回デプロイの手順

審査通過メールに記載されたSVN URLをcheckoutし、trunkにプラグインファイルを配置してsvn add → commitするだけです。開発用ファイルを含めないことだけ注意してください。

審査通過メールが届いたところから、順を追って説明します。

▲ WordPress.orgからの審査通過メール

Step 1：リポジトリをcheckoutする

審査通過メールに記載されたSVN URLを使います。

svn checkout https://plugins.svn.wordpress.org/rapls-pdf-image-creator/ wporg-svn
cd wporg-svn

1 2	svn checkout https://plugins.svn.wordpress.org/rapls-pdf-image-creator/ wporg-svn cd wporg-svn

wporg-svnは作業フォルダの名前で、好きな名前でOKです。checkoutが完了すると、trunk/・tags/・branches/・assets/の空ディレクトリが見えるはずです。

▲ checkoutしたディレクトリ構成

Step 2：trunkにプラグインファイルを配置する

プラグインのコードをtrunkにコピーします。

wporg-svn/
  trunk/
    rapls-pdf-image-creator.php   ← メインファイル
    readme.txt                    ← 必須
    includes/
    css/
    js/
    languages/
  assets/                         ← 画像は後で配置
  tags/
  branches/

wporg-svn/

trunk/

rapls-pdf-image-creator.php ← メインファイル

readme.txt ← 必須

includes/

css/

js/

languages/

assets/ ← 画像は後で配置

tags/

branches/

ここで注意すべきは、開発用のファイルを含めないことです。.git/、node_modules/、.env、テスト用ファイルなどはtrunkに入れないでください。WordPress.orgは配布用なので、ユーザーに必要なファイルだけを置きます。

Step 3：svn addしてcommitする

svn add trunk/* --force
svn commit -m "Initial release: version 1.0.0" --username あなたのWordPress.orgユーザー名

1 2	svn add trunk/* --force svn commit -m "Initial release: version 1.0.0" --username あなたのWordPress.orgユーザー名

初回commitではWordPress.orgのユーザー名とパスワードの入力を求められます。--usernameオプションでユーザー名を指定しておくとスムーズです。

--forceを付けると、ディレクトリ内のファイルを再帰的にすべて追加してくれます。

assets（バナー・アイコン・スクリーンショット）の設定

assetsはプラグインページの見栄えを大きく左右します。リポジトリ直下のassets/にファイル名・サイズが仕様通りの画像を置いてcommitしてください。反映まで数時間かかることがあります。

プラグインページの見栄えを大きく左右するのがassetsです。ここをちゃんと設定するかどうかで、ユーザーの印象がまったく変わります。

バナー画像

プラグインページのヘッダーに表示される横長の画像です。

ファイル名	サイズ	用途
banner-772×250.png	772×250px	標準ディスプレイ用
banner-1544×500.png	1544×500px	Retinaディスプレイ用

ファイル名は完全に一致させる必要があります。Banner-772x250.png（先頭大文字）でもダメです。

アイコン画像

検索結果やプラグイン一覧に表示される正方形の画像です。

ファイル名	サイズ
icon-128×128.png	128×128px
icon-256×256.png	256×256px

スクリーンショット

プラグインの動作画面を見せる画像です。readme.txtの== Screenshots ==セクションと番号が連動します。

== Screenshots ==

1. プラグインの設定画面
2. PDFアップロード時のサムネイル自動生成
3. メディアライブラリでの表示

== Screenshots ==

1. プラグインの設定画面

2. PDFアップロード時のサムネイル自動生成

3. メディアライブラリでの表示

この「1.」「2.」「3.」が、screenshot-1.png、screenshot-2.png、screenshot-3.pngと対応します。

assetsを配置してcommitする

画像ファイルをリポジトリ直下のassets/に配置します。繰り返しますが、trunk/assets/ではなくassets/です。

wporg-svn/
  assets/
    banner-772x250.png
    banner-1544x500.png
    icon-128x128.png
    icon-256x256.png
    screenshot-1.png
    screenshot-2.png

wporg-svn/

assets/

banner-772x250.png

banner-1544x500.png

icon-128x128.png

icon-256x256.png

screenshot-1.png

screenshot-2.png

▲ assets/ディレクトリの中身

svn add assets/* --force
svn commit -m "Add plugin assets: banner, icon, screenshots"

1 2	svn add assets/* --force svn commit -m "Add plugin assets: banner, icon, screenshots"

commitしてから実際にプラグインページに反映されるまで、数分〜数時間かかることがあります。WordPress.orgはCDNを使っているので、キャッシュが効いている間は古い状態が表示されます。焦って何度もcommitし直すと履歴が汚れるだけなので、しばらく待ってください。

▲ プラグインページにバナーが表示されている状態

Stable tagとtagsの関係——リリースの仕組みを理解する

WordPress.orgはreadme.txtのStable tagの値を見てユーザーに配布するバージョンを決定します。Stable tag・PHPヘッダーのVersion・tags/ディレクトリ名の3つを必ず一致させてください。

WordPress.orgでいちばん混乱しやすいのが、readme.txtのStable tagとtags/ディレクトリの関係です。ここを正しく理解していないと「更新したのに反映されない」「古いバージョンが配布されている」というトラブルが起きます。

Stable tagとは

readme.txtの先頭付近にある以下の行です。

Stable tag: 1.0.0

1	Stable tag: 1.0.0

WordPress.orgはこの値を見て、ユーザーにダウンロードさせるバージョンを決定します。Stable tag: 1.0.0と書かれていれば、tags/1.0.0/の中身が配布パッケージになります。

つまり流れはこうです。

trunkにコードを置いて開発する
リリースの準備ができたら、readme.txtのStable tagを更新する
svn copyでtrunkの内容をtagsにコピーしてバージョンを固定する
WordPress.orgがStable tagの値を読み、対応するtagsのコードを配布する

実際のリリース手順

バージョン1.0.0をリリースする例です。

# 1. trunkのコードを最終状態に整える（テスト完了済み）

# 2. readme.txtのStable tagとバージョンを更新
#    Stable tag: 1.0.0
#    メインファイルのVersion: 1.0.0 も一致させること

# 3. trunkをcommit
svn commit -m "Release prep: version 1.0.0"

# 4. trunkからtagsにコピー（これがリリースの確定操作）
svn copy trunk tags/1.0.0 -m "Tag version 1.0.0"

# 1. trunkのコードを最終状態に整える（テスト完了済み）

# 2. readme.txtのStable tagとバージョンを更新

# Stable tag: 1.0.0

# メインファイルのVersion: 1.0.0 も一致させること

# 3. trunkをcommit

svn commit -m "Release prep: version 1.0.0"

# 4. trunkからtagsにコピー（これがリリースの確定操作）

svn copy trunk tags/1.0.0 -m "Tag version 1.0.0"

▲ svn copy（tag作成）の実行結果

次のバージョン（1.0.1）をリリースするとき

# trunkで修正作業を行う

# readme.txtとメインファイルのバージョンを1.0.1に更新
# Stable tag: 1.0.1

svn commit -m "Release prep: version 1.0.1"
svn copy trunk tags/1.0.1 -m "Tag version 1.0.1"

# trunkで修正作業を行う

# readme.txtとメインファイルのバージョンを1.0.1に更新

# Stable tag: 1.0.1

svn commit -m "Release prep: version 1.0.1"

svn copy trunk tags/1.0.1 -m "Tag version 1.0.1"

この繰り返しです。慣れると5分もかかりません。

「Stable tag: trunk」はやめておいたほうがいい

Stable tag: trunkと書くと、trunkの最新状態がそのまま配布されます。tagを切る手間が省ける反面、作業途中のコードがうっかりユーザーに配布されるリスクがあります。

私は最初「tagsを切るのが面倒だから」とtrunkにしていた時期がありましたが、一度trunkに中途半端な状態でcommitしてしまい、その状態がしばらく配布されていたことに気づいて冷や汗をかきました。それ以降はtagsを切る運用に変えています。手間と言ってもsvn copyの1行だけなので、安心のために必ずtagsを使うことをおすすめします。

バージョンの不一致に注意

以下の3箇所のバージョン番号は必ず一致させてください。

readme.txtのStable tag:
メインPHPファイルのヘッダーコメントのVersion:
tags/のディレクトリ名

ここがズレていると、WordPress管理画面で「更新あり」の通知が正しく出なかったり、古いバージョンが配布され続けたりします。

GitHubで開発してSVNで配布する——現実的なワークフロー

開発はGitHub、配布はWordPress.org SVNと役割を分けるのが現実的です。リリース時にtrunkの中身を差し替えてcommitし、tagsにコピーするだけで同期できます。

実際の開発では、コードの管理はGitHubで行い、WordPress.orgのSVNにはリリース時だけ同期するのが現実的です。私もこの方法で運用しています。

なぜこの方法がいいのか

GitHubなら、ブランチを切って機能開発したり、プルリクエストでコードレビューしたり、GitHub Actionsでテストを自動化したりと、モダンな開発フローが使えます。一方でWordPress.orgのSVNは配布に特化しているので、開発の履歴を置く場所としては向いていません。

「開発はGitHub、配布はSVN」と役割を分ければ、両方の良いところを活かせます。

手動での同期手順

# 1. SVN作業コピーを最新化
cd wporg-svn
svn up

# 2. trunkの中身を差し替え
rm -rf trunk/*
cp -r /path/to/github-repo/dist/* trunk/
# ※ distフォルダがない場合は、開発用ファイルを除外してコピー

# 3. 変更をSVNに反映
svn add trunk/* --force

# 削除されたファイルがあれば一括処理
svn status | grep '^!' | awk '{print $2}' | xargs svn delete

svn commit -m "Release 1.2.0"

# 4. tagを切る
svn copy trunk tags/1.2.0 -m "Tag 1.2.0"

# 1. SVN作業コピーを最新化

cd wporg-svn

svn up

# 2. trunkの中身を差し替え

rm -rf trunk/*

cp -r /path/to/github-repo/dist/* trunk/

# ※ distフォルダがない場合は、開発用ファイルを除外してコピー

# 3. 変更をSVNに反映

svn add trunk/* --force

# 削除されたファイルがあれば一括処理

svn status | grep '^!' | awk '{print $2}' | xargs svn delete

svn commit -m "Release 1.2.0"

# 4. tagを切る

svn copy trunk tags/1.2.0 -m "Tag 1.2.0"

ポイントはsvn status | grep '^!'の行です。trunkからファイルを削除した場合、手動でsvn deleteしないとSVNが認識してくれません。この1行でまとめて処理できます。

GitHub Actionsで自動化する

毎回手動で同期するのが面倒になったら、GitHub Actionsで自動化できます。10up（WordPress専門の大手開発会社）が公開しているActionが定番です。

10up/action-wordpress-plugin-deploy

GitHubでリリースタグをpushすると、自動でWordPress.orgのSVNにデプロイしてくれます。設定方法は10upのGitHubリポジトリにドキュメントがあります。

私はまだ手動運用ですが、リリース頻度が増えたら自動化に切り替える予定です。

TortoiseSVN——Windowsで使えるGUIクライアント

コマンドラインに抵抗がある方にはTortoiseSVNがおすすめです。Windowsのエクスプローラーに統合され、右クリックメニューからSVN操作ができます。

コマンドラインでの操作に抵抗がある方は、TortoiseSVNという選択肢があります。Windowsのエクスプローラーに統合され、右クリックメニューからSVN操作ができるGUIツールです。

▲ TortoiseSVNの右クリックメニュー画面

よく使う操作

やりたいこと	TortoiseSVNの操作	対応するコマンド
作業コピーを作る	右クリック → SVN Checkout	`svn checkout URL`
最新化する	右クリック → SVN Update	`svn update`
変更状態を確認	右クリック → Check for Modifications	`svn status`
差分を見る	右クリック → TortoiseSVN → Diff	`svn diff`
コミット	右クリック → SVN Commit	`svn commit -m "msg"`
ファイルを追加	右クリック → TortoiseSVN → Add	`svn add PATH`
タグを作成	右クリック → TortoiseSVN → Branch/Tag	`svn copy SRC DST`
履歴を見る	右クリック → TortoiseSVN → Show log	`svn log`
変更を取り消す	右クリック → TortoiseSVN → Revert	`svn revert PATH`
ロックを修復	右クリック → TortoiseSVN → Cleanup	`svn cleanup`