How to Publish a Plugin to the WordPress Plugin Directory

Recently I published one more plugin to the wordpress.org repository and I decided it is time to share the whole process with you.

This is not going to be the guide how you need to develop your own plugin in order for it to be accepted by the moderators team, the long story short – just read the guidelines, make sure that any user input is properly validated and sanitized, any output is escaped, turn on WP_DEBUG while developing and make sure that there are no PHP notices etc.

Submitting a Plugin to wordpress.org

readme.txt

First things first your plugin should contain a readme.txt file in its folder. This file is parsed for plugin information and also used to display the content on the wordpress.org plugin’s page.

Example:

=== Plugin name ===
Contributors: rudrastyh
Tags: tag1, tag2, tag3
Requires at least: 3.1
Tested up to: 6.3.1
Stable tag: 1.1
Requires PHP: 5.3
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html

This is a short description, 150 chars max, will be displayed in search results on wordpress.org.

== Description ==

This is a long description which is going to be displayed on the plugin page itself.

It may have some subheading and additional formatting.

= Subheading =

For example we can describe some free version features here and below just display the link to the pro version of the plugin.
1. Feature one
2. Feature two
3. etc

[Link text here](https://rudrastyh.com/plugins)

== Installation ==

1. The first step
2. The second step
3. And of course the third step with some **bold text**

== Frequently Asked Questions ==

= Question 1 =
Answer 1

= Question 2 =
Answer 2

== Screenshots ==
1. First screenshot description
1. Second screenshot description

== Changelog ==

= 1.1 =
* Bug fixes

= 1.0 =
* Initial release

Now let’s dive into it and begin with the first part, plugin headers:

  • It is not necessary to provide all the headers, the required ones are only: Contributors, Tags, Tested up to, Stable Tag and License. It means that you can easily remove Requires PHP and License URI for example and nothing will happen.
  • Since WordPress 5.8 Requires PHP and Requires at least are going to be used from plugin’s main PHP file.

As you can see there is a lot more into readme.txt file than just the plugin information (headers), so probably it will handy to use the official readme validator tool to make sure that everything is correct in the file. The rest of the file is split into sections, each of them can have its own content.

  • You can use markdown, specifically == heading 2 == (tab name), = heading 3 =, ** bold text **, * italic text *, [link text](link URL), `<?php code() ?>`, also you can start a new line with a number in order to create an ordered list or start a line with an asterisk in order to create an unordered list.
  • “Screenshots” section is fully optional and needed only if you would like to display description under each of the screenshots, but it is totally enough just to upload the files into assets folder.
  • Subheadings = Question 1 = and the text underneath them Answer 1 in “Frequently Asked Questions” section will be transformed into a nice accordeon.

Uploading the plugin to wordpress.org

Once your plugin is ready, let’s upload it! It is easy as pie, all you need to do is to:

  1. Create an account on wordpress.org if you still don’t have one.
  2. Go to this page, upload the plugin and you’re done.

Here is how it looks like:

submitting a plugin to the WordPress plugins directory
At the moment of uploading a free version of my inventory sync plugin there were more than 1000 plugins waiting for the review, so yes, I waited for 3 months before my plugin got reviewed.

The long story short let’s assume that you submitted your plugin, later it got approved and you received a email from the WordPress reviewers team with the plugin repository information 🎉

So, now it is time to learn how to manage it.

Managing Plugins with SVN

SVN (Subversion) – is a version control system which is used in WordPress plugin repository, yes, like GitHub.

In order to upload your plugin to WordPress servers you need to learn how to use it. It is not that difficult by the way and you have a choice – you can use an application with GUI, like Versions or something or Terminal. In this tutorial I am going to cover both ways.

Install SVN on MacOS

First things first let’s check whether SVN is already installed on your computer. It is as easy as running svn --version in MacOS terminal.

Mac OS terminal – Subversion is not installed
SVN is not installed: “command not found: svn”.

Not installed for you as well? Let’s run brew install subversion and wait till finished. Well, in that case maybe you will need to visit HomeBrew website and install it as well beforehand.

That’s pretty much it.

Or if you’re about to use a GUI SVN client, then you just install it as any other application, nothing special.

SVN URL and Public URL

When you got a “your plugin has been approved” email from WordPress reviewers team, you can find your plugin Public and SVN URLs in that email.

The Public URL is just a URL of your plugin page on wordpress.org, it may look like this:

The public page of a plugin in wordpress.org plugin repository
As you can see, from the very beginning this page is not available for the public yet.

The SVN URL is what we are going to use to publish plugin files, to release new versions or just to edit readme.txt and upload some new screenshots.

Let’s start with something simple – let’s connect to the SVN URL and check what is in it.

You can copy and paste the following command into the terminal:

svn list --recursive https://plugins.svn.wordpress.org/inventory-sync-for-woocommerce

Or svn ls -R https://plugins.svn.wordpress.org/inventory-sync-for-woocommerce if you prefer to keep the things simplified. When we’re using the --recursive or -R flag we mean that all the subfolders should be displayed as well.

list files and directories inside a plugin SVN URL

We can also do the same in a subversion application by clicking on a “New repository bookmark” button (or something like this).

List of subdirectories inside of a WordPress plugin SVN repository

As you can see in both cases we have the same list of directories displayed. In the next chapter of this tutorial we are going to talk about every directory in details.

File structure

DirectoryPurpose
assetsThe plugin assets go into this directory (icons, banners and screenshots).

In order to add screenshots, you need to use the following naming: screenshot-{NUMBER}.(png|jpg|jpeg|gif) for example screenshot-1.png.

For plugin icons you can use: icon-128x128.(png|jpg), icon-256x256.(png|jpg) and icon.svg.

For banners: banner-772x250.(jpg|png), banner-772x250-rtl.(jpg|png), banner-1544x500.(jpg|png), banner-1544x500-rtl.(jpg|png)
tagsIn this directory all the plugin versions are stored in subfolders like 1.0, 2.0, 2.2.1 etc

By the way, readme.txt file from the latest version from here is going to be used.
trunkIt is where the stable version of your plugin should be.

Uploading the files into the WordPress repository

First of all we need a local directory which is going to be kind of a mirror of the SVN repository of your plugin on wordpress.org servers. You can choose absolutely any directory for that. For example I want to use Sites/svn and I can create this folder in three different ways:

  1. I can either create it manually
  2. or using the terminal commands cd Sites/svn and then mkdir inventory-sync-for-woocommerce
  3. or just with a single command mkdir -p Sites/svn/inventory-sync-for-woocommerce.

Now we need to checkout (to pull) the SVN directory from WordPress servers to our new empty directory. In order to do it we need to run a command svn co or svn checkout.

svn co https://plugins.svn.wordpress.org/inventory-sync-for-woocommerce

Make sure that you’re running this command from the parent directory (in our case svn).

That’s my result in the terminal:

checkout a remote directory using SVN
As you can see I’ve already uploaded 1.1 version of the plugin on the server before. Now we pull all of that into our new folder.

If you’re using a SVN client application, it may look something like this:

Checkout (pull the remote directory) while using Versions app

As a result your local working directory is going to be displayed like this:

connected local and remote directories in Versions

Now, once local and remote directories are connected we can make some changes and commit them to the servers!

If you haven’t just made the checkout thing, then it would be great to get in sync with the latest changes in the SVN repository, you can either click an “Update from repository” button (or something like that) or run svn up command in the terminal.

Since you can see on the screenshots that the plugin has already been uploaded in our case, let’s just upload something else, a screenshot for example. Don’t worry, the process is completely the same! So I’ve added a new screenshot-1.png file into the assets folder (because I want to show it as a part of the plugin description on wordpress.org).

Please pay attention to the moment that before doing a commit we first need to “add to the commit” all the new files in the directory. In our case – screenshot-1.png file. You can do it in the terminal with svn add assets/* command or even select a specific file:

svn add assets/screenshot-1.png

When working with our SVN client, we can do it this way:

Add the new files to the next commit in SVN

Ready to commit now!

In the terminal:

svn ci -m 'Hello, it is a new version' --username USERNAME --password PASSWORD

You can skip --username and --password flags but in this case the terminal will ask you for login and password later (it is your wordpress.org profile credentials by the way).

In the SVN app all we need to do is to click the button:

making a commin in SVN using Versions app
You might also notice that we have two changes here, it is just because I also added the information about the new screenshot into plugin’s readme.txt file.

Have any questions left? Let’s discuss them in the comments!

Misha Rudrastyh

Misha Rudrastyh

Hey guys and welcome to my website. For more than 10 years I've been doing my best to share with you some superb WordPress guides and tips for free.

Need some developer help? Contact me

Follow me on X