You built a WordPress plugin. It works. You’ve tested it, packaged it, and you’re ready to make it available to WordPress users.
Then you discover something that surprises many first-time plugin developers:
Publishing a plugin on WordPress.org uses SVN.
Even if you develop your plugin with Git and host the project on GitHub, the official WordPress.org Plugin Directory uses a Subversion (SVN) repository for publishing releases. WordPress describes this repository as a release repository rather than a development repository.
This guide walks through the complete process—from preparing your plugin and submitting it for review to publishing your first release and maintaining future versions.
1. Prepare Your WordPress Plugin
Before submitting anything to WordPress.org, make sure your plugin is production-ready.
Your plugin ZIP should contain the same complete plugin you would install through Plugins → Add Plugin → Upload Plugin inside WordPress.
At minimum, you’ll normally have a structure resembling:
my-plugin/
├── my-plugin.php
├── readme.txt
├── includes/
├── assets/
└── languages/Your main PHP file needs a valid WordPress plugin header. For example:
<?php
/**
* Plugin Name: My Plugin
* Description: A concise description of what the plugin does.
* Version: 1.0.0
* Author: Your Name
* License: GPLv2 or later
* Text Domain: my-plugin
*/Pay particular attention to your Plugin Name and proposed slug. WordPress notes that the plugin URL/slug cannot simply be changed after submission, even though the display name can subsequently change.
2. Create a Proper readme.txt
WordPress.org uses readme.txt for important information displayed in the Plugin Directory.
A basic file might look like:
=== My Plugin ===
Contributors: yourusername
Tags: tools, publishing
Requires at least: 6.5
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
A short description of your plugin.
== Description ==
A longer explanation of what your plugin does.
== Installation ==
1. Install and activate the plugin.
2. Configure the plugin.
3. You're ready to begin.
== Changelog ==
= 1.0.0 =
* Initial release.The Stable Tag deserves special attention.
If your Stable tag is 1.0.0, WordPress.org looks for the corresponding release under /tags/1.0.0/. WordPress also reads the version from the main plugin PHP file, so keeping your PHP version, stable tag, and release tag synchronized is important.
3. Create Your Plugin ZIP
Create a clean ZIP containing the finished plugin.
Do not treat this as an archive of your entire development project. It should contain the files actually required by the WordPress plugin.
WordPress currently instructs developers to submit a production-ready ZIP in the standard WordPress plugin format.
This initial ZIP is for plugin review.
It is not yet your WordPress.org SVN release.
4. Submit the Plugin to WordPress.org
You’ll need a WordPress.org account with a valid email address.
Submit your finished plugin ZIP through the WordPress.org Plugin Directory submission process.
WordPress reviews submitted plugins for issues involving areas such as security, compatibility, guidelines and presentation. If changes are required, the Plugin Review Team will contact you.
This is an important distinction:
Submitting the ZIP does not immediately publish the plugin.
The ZIP is submitted for review and approval.
5. Receive Your WordPress.org SVN Repository
Once your plugin has been approved, WordPress.org provides access to a dedicated Subversion repository.
Its URL follows a structure similar to:
https://plugins.svn.wordpress.org/my-plugin/This is where the publishing workflow changes.
Your development repository might still live on GitHub, but releases distributed through the WordPress.org Plugin Directory are published through the WordPress.org SVN repository.
Understanding the WordPress.org SVN Structure
A WordPress.org repository principally revolves around:
my-plugin/
├── assets/
├── tags/
└── trunk/Each has a different purpose.
/trunk
trunk contains your current plugin code.
For example:
trunk/
├── my-plugin.php
├── readme.txt
├── includes/
└── languages/Your plugin’s root files should go directly inside trunk—not inside another my-plugin directory beneath it.
WordPress specifically warns that placing the whole plugin in a subfolder such as:
trunk/my-plugin/my-plugin.phpcan break the generated plugin download.
/tags
tags contains your releases.
Version 1.0.0 would therefore appear as:
tags/
└── 1.0.0/
├── my-plugin.php
├── readme.txt
└── ...Later you might have:
tags/
├── 1.0.0/
├── 1.1.0/
├── 1.2.0/
└── 2.0.0/WordPress recommends tagging releases and creating those tags from the corresponding code in trunk.
/assets
The repository-level assets directory is used for your WordPress.org Plugin Directory artwork.
That can include things such as plugin icons, banners and screenshots.
This directory is not the same thing as an assets directory inside your actual plugin.
A simplified repository might therefore look like:
my-plugin/
│
├── assets/
│ ├── banner-772x250.png
│ ├── banner-1544x500.png
│ ├── icon-128x128.png
│ └── icon-256x256.png
│
├── tags/
│ └── 1.0.0/
│
└── trunk/6. Check Out the SVN Repository
If you’re publishing manually, you’ll first create a local working copy of the WordPress.org repository.
For example:
svn checkout https://plugins.svn.wordpress.org/my-plugin/ my-plugin-svnYou can then work inside that local SVN repository.
For your initial release, place the production plugin files directly into:
my-plugin-svn/trunk/Then tell SVN about new files:
svn add trunk/*Review the pending changes before committing them.
WordPress requires a commit message for check-ins.
7. Create the Version Tag
Suppose you’re publishing version:
1.0.0Your plugin PHP header should identify that version:
Version: 1.0.0And readme.txt should contain:
Stable tag: 1.0.0Then create:
tags/1.0.0/from the release represented in trunk.
This gives you a relationship like:
PHP Version
│
▼
1.0.0
Stable Tag
│
▼
1.0.0
SVN Release
│
▼
tags/1.0.0/Keeping these aligned prevents a surprising number of publishing problems.
WordPress explains that the Plugin Directory first examines trunk/readme.txt for its Stable Tag. If that points to a valid version under /tags/, the tagged release becomes the relevant source for further parsing. The version displayed for the plugin itself comes from the main PHP plugin file.
8. Commit the Release
Once you’ve reviewed the files and are certain the repository is ready, commit the release.
A simplified manual command might be:
svn commit -m "Release version 1.0.0"This is the point where caution matters.
WordPress SVN isn’t simply another Git development repository.
WordPress specifically advises against using its SVN repository for every small development commit. Commits trigger regeneration of plugin ZIP files, so the repository should contain changes that are actually ready for deployment.
Your GitHub repository can remain where day-to-day development happens.
Think of WordPress SVN as the final publishing destination.
9. Verify the WordPress.org Release
Don’t assume a successful commit means you’re finished.
Visit your WordPress.org plugin page and verify:
- the correct version is displayed;
- the download contains the correct plugin;
- the description is correct;
- the changelog is current;
- the icon and banners display correctly;
- the Stable Tag points to the intended release; and
- WordPress installations recognize the intended version.
This final verification is an important part of a dependable release workflow.
Publishing Future Plugin Updates
Once your first release is live, you’ll repeat much of the process for every new version.
Suppose you’re moving from:
1.0.0to:
1.1.0Your release process generally becomes:
Finish plugin 1.1.0
↓
Update PHP version
↓
Update readme.txt
↓
Update changelog
↓
Build production plugin
↓
Update SVN trunk
↓
Create tags/1.1.0
↓
Review SVN changes
↓
Commit
↓
Verify WordPress.orgAnd then you do it again for the next release.
That’s where managing WordPress plugins through SVN can become repetitive—particularly when you’re maintaining several plugins.
A Simpler Way to Publish WordPress Plugins
The manual SVN process works.
But after publishing multiple plugins, you’re repeatedly doing many of the same things:
build → validate → prepare → update trunk → tag → commit → verify.
That’s exactly why we created WordPress Plugin Publisher.
WordPress Plugin Publisher is a native macOS application designed around the WordPress.org publishing workflow.
Instead of manually assembling each release and managing the SVN process yourself, Publisher guides the release through a synchronized workflow:
Create Release
Build and validate a clean production release of your WordPress plugin.
Prepare Repository
Publisher stages the completed release into the appropriate WordPress.org repository structure while preserving directory artwork when it shouldn’t be changed.
Publishing Intelligence
Before publishing, Publisher checks the pieces involved in the release—including the release package, repository, prepared changes, credentials, documentation, version information and publishing engine.
Publish Release
Once the release is ready, Publisher commits the prepared WordPress.org release and verifies the result.
And if you maintain the plugin on GitHub, Publisher has a separate GitHub publishing workflow for preparing the repository, maintaining README/changelog information, creating the version tag and publishing the GitHub release.
The goal isn’t to replace WordPress.org’s release model.
It’s to make that release model dramatically easier to use.
WordPress.org SVN Without the Command-Line Workflow
For developers comfortable with SVN, WordPress’s manual workflow remains available and well documented.
But you shouldn’t have to become an SVN expert simply because you built a WordPress plugin.
WordPress Plugin Publisher gives Mac developers a visual publishing environment built specifically around the process of getting plugins onto WordPress.org.
Build your plugin. Prepare the release. Validate it. Publish it.
Publisher handles the repetitive parts while keeping you in control of the release.
Ready to publish your WordPress plugin?
Try WordPress Plugin Publisher free for 7 days.
Publish to WordPress.org and GitHub from one native macOS application.
$69/year after the 7-day free trial.