Within this post I will go over the steps necessary to get your plugin hosted by WordPress. This tutorial is for Windows users, but I will link to other tutorials as they become available based on other operating systems. The WordPress directory uses Subversion, which won’t be covered in detail here (you don’t need to know Subversion to follow this tutorial). The tutorial covers adding a plugin I wrote called Feed Styler into the plugin directory. I apologize in advance for the plug, but I wanted to provide a real-world step-by-step example of adding a real plugin.
1. Get a WordPress.org Account
Get over to the WordPress support page and register as a user. You will need to be registered in order to list your plugin.
2. Add Your Plugin
The second step is to add your plugin. You will need to provide:
- Your plugin’s name.
- A one or two sentence plugin description.
- A homepage URI for your plugin (optional).
I recommend always having a dedicated plugin homepage, but that is up to you. You also want to make sure your plugin is GPL Compatible.
3. Wait for Approval
The approval process isn’t overnight. The first plugin I added took about a week, and the second took almost two weeks.
When approved, you will receive an email that says that your plugin has been approved and that you will have access to your subversion repository shortly. In the case of my plugin, the repository was located at: http://svn.wp-plugins.org/feed-styler/
You are also instructed to use the same username and password for WordPress.org to access your repository.
4. Download and Install TortoiseSVN
Head over ot the TortoiseSVN download page and download the appropriate installer (sorry non-Windows users). The installation is relatively painless, but it does require a restart.
5. Create a Directory
Create a directory somewhat out of the way (but easy to find again) that will hold your repository. For the purpose of making this tutorial, I just created a folder on my desktop called ‘feed styler’.
6. Check Out the Repository
Navigate to your new folder and right+click to pull up a context menu with the TortoiseSVN options. What you’ll be wanting to select is SVN Checkout.
TortoiseSVN Context Menu – Checkout
After selecting SVN Checkout, a dialog box will pop up asking for the URL of the repository and the location to store it. The URL to the repository is the one that was e-mailed to you when your plugin was approved. The location to store the repository should already be filled out. After filling in those two pieces of information, simply hit OK.
Subversion Checkout Dialog
If all goes well, you should now have three directories in your folder called branches, tags, and trunk.
7. Prepare Your Read Me File
Prepare your plugin files for being included in the repository. Usually the only thing you have to do for this step is to prepare a Read Me file that adheres to the WordPress.org guidelines. The Read Me creation is straight forward, but WordPress does have a readme validator for your convenience.
Here are some quick tips for preparing your readme file:
- Use appropriate tags when labeling your plugin.
- Store your readme file in your main plugin directory.
- If including screenshots, make sure the screenshots are named screenshot-1, screenshot-2, screenshot-n, etc.
- Use the readme validator to preview your readme file.
- When providing a stable tag, don’t be creative. Use something along the lines of: Stable tag: 22.214.171.124
8. Copy the Plugin Files to the Trunk Directory
Once you have your plugin files in order and a readme file, copy the files to the trunk directory. The main plugin file and the readme should both be at the root of the trunk directory.
In the case of Feed Styler, here is a screenshot of what my trunk directory consisted of:
The Trunk Directory Contents
9. Commit the Files to the Repository
Right+click the trunk directory to bring up the TortoiseSVN context menu. Select SVN Commit.
Commit Context Menu
You will now be presented with a dialog box to enter a log message and to select which files to commit to the trunk. Type in a brief log message (such as “Adding my plugin version”) and select all the files you would like to commit.
Subversion Commit – Log Messages and Files
After you are finished, click OK. You will now be prompted to enter a username and password. The username and password is the same that you use for the WordPress.org Support forums (see Step 1).
If all goes well, your plugin files should be added.
Files Added to the Trunk
10. Tag Your Plugin Release
This is where the readme file really comes into play. In the readme file, there was a spot to add in a stable tag (in my case 126.96.36.199). You will want to provide a tag that matches the stable tag in the readme file.
Right+click the trunk directory and select TortoiseSVN » Branch/Tag.
Adding a Tag Context Menu
Within the dialog that pops up, type in the path to your tag directory and the version. In my case, it was: http://svn.wp-plugins.org/feed-styler/tags/188.8.131.52
Also, type in a quick log message that more-or-less says, “Tagging this release.” Hit OK when you are finished.
Tagging Dialog Box
If all goes well, the plugin should now be tagged and ready to go. You may want to update your tags directory (locally) by right+clicking the tags directory and clicking SVN Update.
11. Make Sure Everything is Accurate at the Repository and the WordPress Plugin Directory
There are a few ways to ensure everything went correctly. The best way is to head to your subversion URL (in my case, http://svn.wp-plugins.org/feed-styler/) and ensure the trunk and tags were uploaded successfully.
After committing the initial trunk or tags, the WordPress plugin repository takes about fifteen minutes to update. After that, head over to your plugin’s URL at the plugin directory (in my case, http://www.wordpress.org/extend/plugins/feed-styler) and see if everything in your readme file is appropriately displayed. If you need to make changes to the readme file, simply edit it locally and right+click the file and hit “SVN Commit.”
If all goes well, you should now see your plugin at the front page of the WordPress plugin page.
WordPress Plugin Directory
Thank you for reading my tips on getting your plugin listed at the official WordPress plugin directory. If you have any questions/comments, please feel free to weigh in. I’d like to personally thank Bes Zain for assisting me in taking the screenshots and testing out this tutorial.