Our company builds custom WordPress plugins for clients to be published in the WordPress.org plugin repository. As we are about to publish another client plugin it's a great time to write about the processes for submitting a plugin to the WordPress plugin repository. Note this post is only about submitting your plugin; we'll cover actually publishing your plugin in the future.
The "Add Your Plugin" Page
First you need to request plugin hosting at WordPress.org using the "Add Your Plugin" page on WordPress.org. This page request three (3) bits of information:
- Name of the plugin
- Description of plugin
- URL from where your plugin can be downloaded.
Select a Good Name
Naming your plugin may seem a trivial step but there are both technical and marketing issues to consider.
The Plugin URL
The name you provide drives the URL for your plugin's page on WordPress.org. Let's look at the related URLs of some popular plugins and some of our client's plugins, in no particular order:
|Plugin Name||Plugin URL|
|Jetpack by WordPress.com||http://wordpress.org/extend/plugins/jetpack/|
|WP Super Cache||http://wordpress.org/extend/plugins/wp-super-cache/|
|RevoStock Media Gallery||http://wordpress.org/extend/plugins/revostock-gallery/|
|Google Analytics for WordPress||http://wordpress.org/extend/plugins/google-analytics-for-wordpress/|
|W3 Total Cache||http://wordpress.org/extend/plugins/w3-total-cache/|
|All in One SEO Pack||http://wordpress.org/extend/plugins/all-in-one-seo-pack/|
|Contact Form 7||http://wordpress.org/extend/plugins/contact-form-7/|
With one exception ("Jetpack by WordPress.com") the name of the plugin matches the 'URL Slug.' The URL Slug is equivalent to the URL slugs assigned to blog posts in WordPress; the last URL path segment with all alpha characters lowercased, spaces converted to dashes and any other characters besides numbers removed.
With everything else equal we're fans of shorter URLs and we really like the URLs for JetPack, Content.ad and Pardot. We are less excited about the URL slug for one of our client's plugin; Content.ad with the missing dot ('.'), but such is life.
Update after Submission (Maybe)
Consider the name vs. URL slug for Jetpack; obviously the name is longer than the URL slug meaning the name was changed after it was submitted, or maybe the WordPress.com team modified the URL which is something you can't do. But it really doesn't matter because you can get the URL you'd prefer if you are proactive.
Our Proposed URL Naming Strategy
Submit with a short plugin name to capture an appropriate short URL. Then if you really need to you can embellish your plugin's name when you publish your plugin as was done by the JetPack team when they added "by WordPress.com".
Use your One Most Important Keyword
People are constantly on the hunt for plugins that better meet their needs than those they've already tried. They often search the repository by keyword and having your plugin appear in the search results for your most important keyword is obviously a plus.
Some of the plugins above include the words "cache", "seo", "media" and "form" in their names. If your plugin is targeting a selected group of users, for example online store owners you might include terms to peak their interest, such as "(shopping) cart", "store", or "(e-)commerce".
But don't overdo it either. WordPress users are saavy and if they see a plugin name stuffed with keywords they'll probably pass it by and look for a plugin developed by someone more interested in building a useful plugin than gaming the search engines.
Of course this recommendation seems completely obvious but I've been surprised at how many plugins either don't do this or go overboard.
Just Say "No" to "for WordPress" or "WordPress Plugin" in the Name
You shouldn't add "for WordPress" or "WordPress Plugin" or even "Plugin" to your plugin's name; it's all implied. Pippin Williamson of Pippin's Plugins pre-reviewed this post and said the WordPress plugin review team no longer allows the use of these terms in the plugin name.
We do think it makes good sense to use these terms when describing your plugin on websites where it's not clear it's a plugin for WordPress, such as on your own website, but you don't need to for the name used in the repo and evidently you are no longer allowed to anyway.
UPDATE: Otto from the plugin review team confirmed that not only does the plugin review team no longer allow this the plugin submission form won't even submit when you have "WordPress" in the plugin name. So plan accordingly.
And Don't Name your Plugin with a Run-on Sentence
Here let's take a look at the banner image of an existing plugin we found in the repository that has a really long name and "for WordPress" in the name:
If we were publishing this plugin we might use the following name instead; hopefully you can appreciate the difference?
Also note how we used Capital Case except Prepositions, Articles or Conjunctions for our proposed plugin name. For the plugin name use-case, title case just reads easier.
Write a Clear Description but Don't Stress Over It
Writing your plugin's description is much less stressful than selecting its name. The description is used for two (2) reasons:
To Inform the WordPress Plugin Team about your plugin. Write this with a mind to make it easier for them to evaluate your plugin.
As Placeholder Content on WordPress.org to be used immediately upon hosting approval. The good news is you can change any time you push your plugin to the repository so no need to stress over getting it perfect on submission, just make sure it is not embarrassing.
This is what your plugin page will look like on WordPress.org immediately after the plugin is approved. Note that we used this plugin and did surgery on the screenshot to get the effect since we didn't have a "just approved" plugin to screenshot:
Make your Plugin Available for Download via URL
At the start of this post we wrote "The first step to publishing a plugin is to request plugin hosting at WordPress.org" but that's not technically correct. The very first step is to actually develop and test a working plugin!
Test it First
Your plugin doesn't necessarily need to be feature complete nor be tested for every potential use-case but it does need to work and its working features should accurately represent its functionality. During the review process the team will try to install it and if it breaks or won't install they will reject it.
The Plugin Team are Not your Beta Testers
Remember the WordPress plugin review team are volunteers, and they are not your beta testers; send it in too many times broken and they may ban your plugin from the repo. But even if they won't ban you it's better to just make sure your plugin works the first time so as not to slow down your plugin's launch.
After you Press "Send Post"
After you submit your plugin your request for hosting will queue for one of the volunteers on the team to review.
Provide any Account or Login Required for Plugin Review
If your plugin requires an account or a login you'll need to provide to the plugin team especially if they can't request for free online. You can either include your plugin's description or email to firstname.lastname@example.org and include "Account for <Your Plugin Name> Plugin" in your email's subject line. We prefer to email so they don't accidentally approve the plugin without first removing the account/login.
For your account/login's email address use email@example.com so anyone on the plugin team can access it. We wish the plugin team would add a "Notes:" field on the submission form but unless and until they do this is our workaround.
Follow Guidelines/Best Practices and Don't be Evil™
They will install and inspect your plugin for errors and for reasonable quality code. They will review it against the list of guidelines and internal list of best practices, and they will also give it "the smell test" to ensure your plugin is not evil (i.e. that it has no spammy behavior and that it doesn't do anything else that would rightly annoy users.) "Fail" any of these tests and your request will be put on hold until you resolve the issue.
Then You Get to Wait…
Once you've submitted it can take from a day to several weeks before you get a response. In our experience it's always been just a few days but this is a volunteer team and hosting is a privilege offered for free so don't look a gift horse in the mouth. Be ready to wait a few days, if that's what it takes.
But if it really is taking a long time you can verify they received your request by emailing firstname.lastname@example.org. But remember it's best not to become the plugin submitter who wins the award for the most annoying person of the day if you ever want to see your plugin published; why tempt fate?
And Finally, Approval!
And then finally if approved you will get an email with a subject line of:
[WordPress.org Plugins] Request Approved: <your-plugin-slug>
And the following will be in the body of your email:
<Your WordPress.org Account Name>, Your plugin hosting request has been approved. Within one hour, you will have access to your SVN repository at http://plugins.svn.wordpress.org/your-plugin-slug/ with your WordPress.org/bbPress.org username and password (the same one you use on the forums). Here's some handy links to help you get started. Using Subversion with the WordPress Plugins Directory http://wordpress.org/extend/plugins/about/svn/ FAQ about the WordPress Plugins Directory http://wordpress.org/extend/plugins/about/faq/ WordPress Plugins Directory readme.txt standard http://wordpress.org/extend/plugins/about/readme.txt readme.txt validator: http://wordpress.org/extend/plugins/about/validator/ Enjoy!
Now you are home free!
The next step is to actually publish your plugin but that's the subject of a future post.
And if your Plugin is Not Approved?
If your plugin fails their review they will email you and generally be quite cordial while explaining their concerns. Often it is as simple as ensuring you use the version of jQuery included with WordPress rather than bundling it. Just fix the problem, upload a new version and let them know via email.
Again, Don't be Evil™
Of course if your plugin is attempting to do something really nasty like downloading the users table then they won't be cordial at all. But we've got absolutely no reason to expect you'd do that, right? Right.
Don't Expect Miracles, Have a Plan
When you've finally gotten your plugin added to the WordPress.org plugin repository people will be able to find it by searching, by tags and several other ways. But realize there are over 23,000 plugins listed and we guesstimate about 15-20 new plugins a day. With so many plugins to compete for attention just publishing your plugin isn't likely to drive a rush of downloads. So make sure you plan a marketing campaign or at least have a marketing strategy if you want your plugin to be successful.
And for you TL;DR people, here's a high level summary:
- Visit the "Add Your Plugin" Page
- Select a Plugin Name
- Consider the URL
- Embellish after submission
- Use most favored keyword
- Don't add "for WordPress" or "WordPress Plugin"
- No super extra very long plugin names
- Use Title Case
- Write a Clear Description
- Post your Plugin for Download
- But test, test test!
- Be considerate of the plugin team
- Once you've Submitted
- Be Realistic, Have a Marketing Plan
Related Links and Posts
We're not the first to write about submitting plugins so here are other links you might find helpful. Most of these cover the entire publishing process whereas we've just covered submission. We'll cover the publishing process in a future post but these should tide you over until then:
Submitting to the WordPress Plugin Directory - WordPress Codex/Plugin Submission and Promotion
How to Submit a WordPress Plugin - Support thread on WordPress.org (2012)
Follow up Posts
If you found this post helpful you'll probably also want to read the following post we've since added too:
Call for Comments?
Did we miss anything, or get anything wrong? Suggestions for update? Let us know below.