With the WordPress Plugin Competition 2.0 in full swing, some plugin authors may want to have their plugin listed at the official WordPress.org Plugin Directory.
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.
TortoiseSVN Installer
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: 1.0.5.0
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).
Login Screen
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 1.0.5.0). 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/1.0.5.0
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
Conclusion
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.
This (very nice) post is in itself a proof that there’s something awfully wrong with getting one’s plugin listed on wp.org. One word: cumbersome. Something like wp-plugins.net is simple and very efficient. Having to use SVN to upload a simple plugin is totally overkill. In 95% of cases, a plugin is a one-coder no-update piece of code. That’s not what SVN was created for.
Mark, Adjay: what is the purpose of asking Plugin Competition contestants to get their plugin hosted on wp.org? WP.org needs no exposure, so I guess this requirement is here to make sure plugins have the maximum visibility and availability, right? If so, why not ask for an optional plugin page AND a mandatory upload, either on wp.org or wp-plugins.net ?
Wow there is a lot involved in listing a plugin!
TortoiseSVN is indeed only for Windows users… but that’s only because Mac and Linux users already have the original tools to work with: svn.
Checkout is made via: svn co –username
Checkin is simpler: (while at the local folder) svn ci
Tagging is like: (whila at local folder’s parent) svn copy
Did I mention that no reboot is needed? Or that several GUIs exist for it?
Ozh, there is no requirement for the plugins to be hosted on the WordPress extend. It must be documented is all we require. I am sorry if I confused the issue somehow.
Ozh,
It would be nice if the process was more automated and a little easier. Some of the people with the smaller plugins may be just fine not listing at the official directory. Those with more complicated plugins may find that using the hosed subversion that WordPress offers a life saver. I personally like the benefits of saving bandwidth.
Mark » ho, great! Sounds indeed normal for a plugin. Don’t know why I had this requirement in mind 🙂
Ronald » bandwidth ? 🙂 Come on, any plugin you’d host would weight less than a third of your header images 🙂
Ozh,
I have demonstration videos in the trunk for one of my plugins. At about 1 MB a view, there is definitely some saved bandwidth.
After reading this post I decided that I will not list my chess related plugins on wp.org. At least not now.
Chess Teachig,
Was it something about the post? 🙂 — I’m just curious what your reasons are if you don’t mind explaining.
Thanks for the tutorial, it was really helpful for me as I was just about to add my plugin to the plugin directory. So now it can finally also be downloaded from there: http://wordpress.org/extend/pl.....pleviewer/
Great post Ronald. I recently got approved to host my plugin better comments manager and this will definitely help me.
Nice and very useful information. I wrote my own plugins, but still ain’t familiar to any version control system. I’ve already had a approved folder months ago but it’s still abandoned.. :), hope I can upload my plugins soon.
Although I have not written any WP Plugins yet, I feel it is a good idea for Plugin developers to submit what they made to wordpress.org plugin site. It gives them exposure and creates good central location for quality plugins.
@ Ronald Huereca (question in comment 11)
It was not something about the post. In fact the post makes it even easier, because all the steps are written down very clear.
But it seems like a lot of work for a plugin that is only interesting for the limited group of chess bloggers.
excellent tutorial, I’ve not been able to publish my plugin because I didn’t know how to use SVN. Thanks very much for this post. now my commentluv plugin is available to the world!
Just wanted to thank you for this write-up. I have a very simple plugin and without having to study SVN I have managed to publish the plugin. Thanks Tarkan
After receiving approval for my plugins, I looked everywhere for info on what to do next. No info in the approval e-mail, and the WP site’s ‘easy’ instructions assume I’m already familiar with SVN. Thanks for the tutorial so I can finally get my plugins in a more visible place. To bad it’s going to take more effort to do that than it did to write the plugins in the first place. Perhaps Matt’s next coding project should be a web-based code hosting app for the masses…
Joe,
Please see this support thread.
If it’s been more than a week, submit a bug report. It’s what the moderator of the thread recommends.
I definitely agree on a more automated addition process.
Very informative – and made the submission process much easier for me – thanks! I did have questions about tagging – is it mandatory, or is ‘trunk’ fine for everyone (and if so, does tagging need to be done)? As well, is the tagging number a personal choice, or does WP have a preference on how it works/is formatted?
@David,
You absolutely need to tag. Check out this page for an example.
Each one of the “Other versions” is a tag. The “developmental version” is what is in the trunk. Another word for the developmental version is the “not stable version”. A tagged release is generally stable.
WP does have a preference. Try to keep it only numbers and periods. An example is: 2.0.1.3
You can also do: 2.013
Just make sure your tag matches the tag in your readme file, your main plugin PHP file, and also the name of your tags directory.
Thanks – I obviously have some editing to do for my next plugin…
Thank you. made the procedure of uploading a plugin very easy. I really had no idea.
I downloaded my plugin, and it downloaded the main folder and made the trunk folder a subfolder, with the plugin files it it. Do you know why this may be?
Great post. I was pretty lost until I came across this. I am really liking Subversion…
Once you create a plugin await suggestions and tips how to improve it… although it works. The worst part of creating plugins is that only a few webmasters are willing to donate and thus tell you “thanks!”
Everyone wants plugins, but they don’t come out of nowhere. Coders must learn all the time, they must understand the needs and so on…
This post was very useful for a first timer… it really helped me figure it all out. Thank you very much 🙂
Thanks for the great tutorial, I had no idea what I was doing until I found this.
Thanks for a great tutorial. First tried and first worked so cheers for making my first WordPress plugin upload experiance, not too frustrating!
Not sure about the tag part and why you MUST do it however! I see the advantage but for now I’m doing to skip it and get my CSV 2 POST plugin released. Then start getting some feedback then tag it.
Someone mentioned how creating plugins does not get much donations from webmasters. I plan to put a timer on my plugin that requires donation after being installed for a certain period AND used a certain number of times. Basically put a guilt trip on the user.
I was told this is ok under GNU because you have provided the software free, how it operates is up to you. Something I think many plugin developers are failing to take advantage of and it’s about time a little more revenue came from them.
My CSV 2 POST plugin page…
http://www.webtechglobal.co.uk.....ost-plugin
Now in the WordPress Plugin directory thanks to this tutorial
Ryan
Just noticed Ozh’s comment. What a ramble. Ozh you have basically stated yourself there is choice so if you do not like this option why ramble on about it?
This blog post is a tutorial for those taking this option and your comment is bashing the wrong person for the wrong reasons.
Plus I agree with Jenny. The process I just went through for the first time after following this tutorial was not so big. Every step seems to be for assurance, security and accurancy which is a small price to pay for develivering a BIG plugin.
Give me a plugin example that does not need updates after launch also? One that gets used and is popular because all my currently installed plugins (35) on all my blogs get weekly updates.
Ryan
WebTechGlobal
i just wish more ppl would put there plugins in the plugins dir so everyone find the plugin they r lookgin for & also knowing that the plugin your getting is coming from the WP dir give it a but more trust
i’m sure they would not let ppl add plugins that have something hiden in side of it that could be bad in some way
Hey
Any chance of a small tutorial for adding the next version to your repository then committing it but preventing a folder being removed or overwritten in a users current installation of a plugin on wordpress.
Did that make sense lol
Basically on Tortoise I selected Delete/Ignore but what it done was actually removed it from the version on wordpress.org. This then resulted in deletion of the specific file from users installation of my plugin. Totally opposite effect to what I read and expected so I need to admit I’m confused and will read then comment on any content you make regarding this.
Hi Mark,
Just wanted to say thanks – I’ve finally decided that any new plugin I release is going into the repository, starting with one I just finished (Comment Warning). Couldn’t have got in there without this post so thanks.