Once you’ve created and tested your first widget, you’re probably in a good position to upload it to the WordPress directory. It’s a great way to get some exposure and recognition for your good work as well as contribute to the community of developers that makes WordPress as powerful as it is.
Submit request to upload plugin
The first step is to submit a request to upload your plugin to wordpress.org. You’ll need an account at wordpress.org if you don’t already have one.
The application form just asks three questions; the plugin name and description, which should be pretty obvious. It then asks for the plugin URL, which is a link to somewhere they can look at your widget. So zip up your plugin folder and upload it to your server (or a file sharing service if you don’t have one) and copy the URL into this box.
Now it’s case of sitting back and taking a break while the admin team review your application. They’ll check that there’s nothing overtly wrong with your plugin (there’s a few guidelines that you need to adhere to) and once they’re happy, you’ll get an email saying that you have had a subversion account set up for you.
Subversion (often abbreviated to SVN) is a system for developing software with multiple developers. It is the way that the WordPress development team and the plugin developers commit their changes to the WordPress directory. It sounds scarier than it really is; if you’ve used FTP software before, this isn’t too dissimilar.
You’ll be given a subversion repository which you can access with your wordpress.org username and password. So now I bet you’re itching to know how to access it aren’t you? Forget your FTP software – you need something new. You’ll need a subversion client. I’m told that the best client for Windows is Tortoise, while I can vouch for Cornerstone on the Mac.
Install and open up your client. You’ll be asked for a server location for your new repository and a username and password to access it. Enter the information as sent to you in the email from WordPress (see picture for a guide).
Once it successfully connects, you should see three folders: branches, tags and trunk. For plugins, you can generally ignore the branches folder, which is used to keep older versions updated with major bug fixes. With plugins, that tends to be handled with normal releases.
That leaves tags and trunk. Tags is where you store the various versions of your plugin. Assuming you start with version 1.0, you’ll create a folder called 1.0 in the tags folder. When you’re ready to release an incremental update, you might create a new folder called 1.1, but we’ll cover that in the next tutorial.
Inside your version folder, you’ll put all the necessary files that go with your plugin. Then there’s just one extra file that we need to include, which is readme.txt.
Creating a WordPress readme file
WordPress uses the readme file that accompanies every plugin to display all the data about the plugin. Every time you look at a plugin in the WordPress directory, it has information about what it is, what has changed between versions and who contributed to it. This is all taken from the readme file, so it’s important to get it right. Fortunately, WordPress have provided a template readme.txt file and a validator which will help identify any issues with it.
Open up the template and save a copy in your plugin folder. Then start editing it. You’ll notice that the first section (Plugin name) contains a lot of the information that is in your plugin header. The contributors should be a list of wordpress.org usernames that contributed to the development of the plugin. You can optionally provide a donate link, where appreciative users of your plugin can donate to you for your efforts. This link appears on the plugin page in the WordPress directory.
‘Requires at least‘ and “Tested up to‘ are referring to WordPress versions – unless your plugin uses functionality that was only introduced in a certain version, it may very well be compatible with a lot of older versions of WordPress.
The stable tag is the newest version that you deem suitable for public release. You could have newer version in your repository that you’re still working on, and this will let WordPress know which version should be provided to users.
Below that goes a brief description that will be displayed under your plugin title in search results.
This is the description that people will see when they open up your plugin page in the WordPress directory, so this is where you want to inform everyone of exactly what your plugin does, so that you can give people a good idea if your plugin is the one they’re looking for. You cannot use HTML here, but you can use markdown which allows links, ordered and unordered lists, bold and italics, and displaying code:
This section is where you can give instructions on how to install your plugin. In most cases, it will consist of little more of telling the user to upload the zip file to the wp-content/plugins/ directory, extracting it and activating it. However, if you have more complicated installation instructions, you can detail them here.
Frequently Asked Questions
Plugin authors receive a lot of questions about their plugins and this is a good opportunity to publicly answer some of those questions to limit the number of queries coming your way. You have to use the markup shown in the readme file to differentiate between questions and answers.
You can take screenshots to show pictures of your plugin in action and WordPress will display them on the Screenshots tab. Take pictures and number the file names sequentially starting with screenshot-1. The file types can either be png, jpg, jpeg or gif. Copy the screenshots into your plugin folder and then add a description for each in the readme file, using the format shown in the template file.
This tab allows you to document how your plugin has changed over time. With each new version, add the new version number at the top of the list and note down the changes (even if it was just a case of bug fixes).
This is a very useful, and underused, section. When you’re updating plugins in WordPress, if the plugin author uses this section, you will get a brief description of the changes in the update screen. This is useful, because if you’ve introduced new features, upgrading users may have no idea unless they go looking for them. So be sure to let them know. Add a new one for each new version.
If you need to add more information to the WordPress directory, you can add a new tab by copying the format for a new tab from the template file.
Upload your first version
Now that you’ve created your readme file, put it through the validator to make sure that you haven’t made any mistakes that will prevent WordPress from displaying it properly. Providing it passes, save it in your plugin folder and you’re ready to upload it.
Create a folder in the tags folder in your plugin repository. The folder will be the version number of your plugin. More than likely, this will be 1.0 at this point in time. Now you can upload all your plugin files to the tags/version.number folder, including the PHP file(s), screenshots, readme file and any accompanying files like images or CSS files.
Once that’s all in place, there’s just one more thing you need to do to have your plugin go live in the WordPress directory. Remember the trunk folder? That’s used for the current files, but we only need to upload your current version of the readme.txt file to the trunk folder. This is because, once it reads the Stable Tag from your readme file in the trunk folder, it will refer to that version under the tags folder for all the rest of the information and the plugin files. So good practice is to update the readme file in your current version folder, and then copy it to the trunk folder.
Going live in the WordPress directory
WordPress scans its repositories every 15 minutes for changes, so once you’ve uploaded all your files, you should expect to see it live within 15 minutes. If you can’t find it after 20 minutes, something is probably wrong with the way you’ve set things up.
So have you uploaded your plugin to the WordPress directory? Why don’t you leave a link to it so I can have a look at it?
Now that version 1.0 is live, you’ll need to know how to make updates to it when you want to create version 1.0.1 or version 1.1. Have a look at How to Update your WordPress Plugin.