Nerd Alert
Navigating the Plugin Directory can be a bit techy.
This article is quite long. Here’s a Table of Contents:
Table of Contents
- Introduction
- Let’s start with my WordPress story
- Why add your plugin to the WordPress Plugin Directory?
- Tips & Tricks Before Launch
- Tips & Tricks After Launch
- Miscelleanous Tips and Tricks
- Conclusion
Introduction
I submitted my first plugin to the WordPress Plugin Directory in 2007. The guidelines weren’t as strict then, and you could actually reserve a plugin name without having to go through a lot of screening.
The guidelines nowadays are more fleshed out. There is a more in-depth screening process. The support system on .org has also improved drastically since its inception.
Navigating .org has gotten more complex, so I figured I’d write an article on it.
Within this article I will go over a series of workflows and tips and tricks covering plugin submission (before and after). This is not necessarily a technical article, so I hope you don’t feel overwhelmed by the information presented here. For existing plugin authors, there may be a few tips here that you may not be aware of.
All opinions are my own unless attributed 🙂
Comments are welcome as always if you have anything to add or share (skip to comments).
Let’s start with my WordPress story
I’ve been in the WordPress game for quite a while now. I first downloaded WordPress in 2006 and have more or less been developing on the platform since.
I have created dozens of plugins, most of them being in the WordPress Plugin Directory. So in other words, I’ve been there and done that when it comes to WordPress plugins.
I’ve responded to what feels like a zillion support posts and have a lot to share about the ecosystem. So first up, why would you want to submit to .org?
Why add your plugin to the WordPress Plugin Directory?
Exposure, collaboration, and easy installation.
I know that maybe that’s not the answer you’re looking for, but the WordPress Plugin Directory has many benefits.
- The WordPress Plugin Directory is already a trusted resource. If you host on your site, you’ll have to earn that trust.
- WordPress itself allows you to search for plugins in the admin. I’d opine that most users add plugins this way. Going to a third-party site, filling in some information, and getting access to the download may be more steps than a user would like to take.
- There’s a dedicated support forum and rating system. You don’t have to build this out yourself.
- You don’t have to worry about licensing or updates. When you publish a new version, it goes out to everyone.
- There’s security support. If a vulnerability sneaks into your plugin, people are more likely to help you than on a third-party site.
- Collaboration. I’ve found that people are more likely to submit a PR or file an issue than with third-party plugins.
Listing your plugin on .org is a great way to get eyeballs on your plugin. If you self-host, adoption of your plugin will take much longer.
Just for the sake of argument, here are some reasons to NOT list your plugin on .org.
Support
Support is a touchy subject for most plugin authors. On one end, you have a public way of diagnosing bugs and building your reputation as a plugin author. On the other hand, some users feel entitled and feel like they’ve made a “purchase” by downloading your plugin.
You need to have a really thick skin when it comes to support. It’s hard taking ratings or angry users personally. After all, your plugin is your baby.
Ratings
These are totally out of your control. Users can leave ratings, even one-stars, and they typically cannot be disputed ninety-nine times out of a hundred (if even that).
Sure, you can throw a #modlook on the rating, but in my opinion, you should leave the moderators out of it and kill the person with kindness.
And a reminder: WordPress forum personnel (e.g., moderators, admins) are all volunteers (i.e., not paid cash money). Be nice.
Support Again
Seriously, you should expect to handle support when releasing a plugin on the WordPress Plugin Directory.
If you have no intention of supporting your WordPress plugin, perhaps it’s better to leave the plugin off WordPress.org.
I’ll be going more in-depth with ratings and support later in this article.
Tips & Tricks Before Launch
Now that we’ve gotten the reasons for listing on .org out of the way, let’s go over some tips & tricks.
Naming your plugin
Naming is the hardest part of a plugin. Some restrictive tips are:
- Do NOT use a trademark in your plugin name (i.e., facebook-share-button)
- Avoid using a company as part of the name (companies come and go, and it’s hard to change the branding later)
One facepalm is when you’ve done all the naming and you find out the plugin slug is taken.
Here’s my tip for that.
Head to: https://plugins.trac.wordpress.org/browser/your-plugin-slug
Replace your-plugin-slug with your desired slug.
If it errors, then the plugin is not taken.
Your are stuck with your plugin slug for life
Make sure you can live with your plugin slug. When you submit it to the repo, the plugin team will create a slug for you based on your plugin upload.
You can change the slug after submission by emailing the plugins team, but once it’s approved, you are stuck with it.
Your Plugin Slug
powerhouse-blocks.Your main plugin file cannot be changed
Let’s say, for example, we have a plugin with the slug: powerhouse-blocks.
Your main file will have your plugin headers and plugin initialization code.
I’ve seen a variety of ways plugin authors name the main file, but let’s go over some examples I’ve seen.
- powerhouse-blocks/index.php
- powerhouse-blocks/main.php
- powerhouse-blocks/powerhouse-blocks.php
- powerhouse-blocks/class-powerhouse-blocks.php
You can’t change the main filename after release because WordPress stores plugin data like just like above.
If people are using, say, powerhouse-blocks/main.php, this will result in an error if you change it and users update.
See, WordPress is looking for your slug plus plugin file. When a plugin is activated, WordPress stores a list of active plugins in a database option (plugin-name/plugin-file.php).
If the file name changes, WordPress will look for your powerhouse-blocks/main.php and be unable to find it. This can lead to accidental plugin deactivation, and if another plugin relies on yours, you can get the white screen of death.
Pick a WordPress folder structure that suits you. Just keep in mind, after submission, it’s set in stone.
If you have to change your main plugin file with something else, keep the plugin headers in the main file and require a helper file that will initialize the rest of the plugin.
It’s kinda an unwritten rule, but for most plugins, the main plugin file mirrors the plugin’s slug.
For example:
powerhouse-blocks/
├─ powerhouse-blocks.php
├─ readme.txtThis makes it super simple for other developers to immediately spot where your plugin starts its execution.
One argument against this is that it breaks WordPress coding standards. But if you want to follow PSR4, you won’t be able to use class-something.php anyway.
Ultimately, your code and file structure is whatever you are comfortable with.
I’d argue there is no right or wrong way to structure your WordPress plugin. Ultimately it is up to you to decide.
Creating a .org account
You are required to create a WordPress.org account in order to submit a plugin.
Creating an account is easy. Just provide a valid email address and a username.
Regarding usernames, if I could go back in time, I would likely make my username my first name + last name.
Do NOT use a company name or company email as your WordPress.org username. This will bite you later if the company changes names and/or goes out of business.
If you are submitting the plugin, you are the plugin author. Even if you’re submitting the plugin on behalf of the company, you will ultimately be responsible for its upkeep.
About your email address…
Submitting the plugin
I’m going to assume your code is complete, secure, and well-tested before diving into this section.
Think of the WordPress Plugin Directory as a host rather than a repository. The Plugin Directory is not intended to be used as a version control system; it’s more of a plugin release system.
WordPress “hosts” your plugin. It isn’t a dev environment.
Excessive plugin commits will peeve the plugin review team. Do your development somewhere else.
When you are ready to submit the plugin, ensure it does not violate the WordPress Plugin Guidelines.
Please do not submit a beta or alpha product to the repo. Ensure your code is production-ready. No code is bug-free, but try to do your due diligence here.
Before you submit…
The readme.txt file should be included in your zip and be in the correct format.
Here are some quick links to help you out.
- readme.txt Overview
- You can preview your readme using the wpreadme.com previewer.
When you’re ready, head over to .org and submit your plugin.
Submitting your plugin can be a nerve-wracking process, especially as minutes turn to hours as you wait for plugin approval. Just bide your time. Your plugin will be addressed, and communication with the plugin team regarding your plugin’s status will just slow down the queue for everyone.
Assuming your plugin is approved, you will receive an email with all of your plugin details and access instructions for SVN. SVN access is usually delayed a bit, so just be patient.
Once SVN access is received, you are now free to take a go at releasing your plugin on .org.
Here are some quick resources:
Optimize your readme.txt
Your plugin’s readme is the first impression your plugin receives. Time and care should be put into the readme to give your plugin the best light.
Here’s a sample readme.txt from a plugin I helped build for Launch with Words. I’ll be using that as an example in this section.
First up is the plugin title. This is the title of your plugin typically. You can also use some keywords in the title to help people find the plugin, but try not to be too spammy.
Launch with Words’ title is as follows:
=== Small Business Copywriting Plugin - Launch With Words ===The rest of the readme header is as follows:
=== Small Business Copywriting Plugin - Launch With Words ===
Contributors: bridgetwillard
Tags: blogging, content marketing, content, writing, copywriting
Requires at least: 5.1
Tested up to: 5.9
Stable tag: 1.0.7
Requires PHP: 5.6
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.htmlCode language: JavaScript (javascript)- Contributors: list all the contributors to the plugin using their .org usernames. This is comma-separated.
- Tags: Comma-separated tags. Try not to use more than 5 tags as going over will have some stripped out.
- Requires at least: What is the minimum WordPress version you will support?
- Tested up to: Which version of WordPress are you compatible with? This is usually the latest version of WordPress.
- Stable tag: If you are utilizing tagging in SVN, you should point to the tag name (version number of the tag).
- Requires PHP: List the minmum version of PHP that your plugin supports.
- License: Which license are you compatible with? Please note that your plugin MUST be GPL.
- License URI: Link to the license.
You’re welcome to also use Donate link: to add a link. Your mileage may vary (don’t get your hopes up). An example:
Donate link: https://github.com/sponsors/MediaRonCode language: JavaScript (javascript)After the header, add a very brief description (max 150 characters and no markup). If you’re having trouble with this, just ask yourself what problem the plugin solves? Chances are you can crank out a small description based on that.
An example snippet:
Allows you to highlight text and enable social sharing to share with services including Twitter, Facebook, LinkedIn, Xing, Telegram, Reddit, WhatsApp, Odnoklassniki, VKontakte, and email.Code language: JavaScript (javascript)Description
This is where you get to put all your main plugin text. You can:
- Use basic HTML
- Use a flavor of Markdown
- Embed a video (make sure it is public and embeddable)
- Add a notice (using the > symbol)
- Add links to products or services
Installation
Just add basic installation procedures here. Link to your docs if you have any available.
Here’s an example.
== Installation ==
1. Just unzip and upload the "post-type-archive-mapping" folder to your '/wp-content/plugins/' directory
2. Activate the plugin through the 'Plugins' menu in WordPress
Post Type Archive Mapping
1. Create a custom post type that has an archive
2. Create a page with a custom template. Use the Gutenberg block to show off posts in that Custom Post Type.
3. Go to Settings->Reading and assign the page to the custom post type archive
4. Go to the post type archive and observe the page content is now the archive
Term Archive Mapping
1. Create a public page to use as your term archive.
2. Visit the edit term page and select the page.
3. View the term and you will see your selected page.
4. Use Gutenberg on your public page to customize the archive.
404 Template Mapping
1. Visit Settings->Reading and map your 404 template to a page.
2. Customize the new 404 page.
3. Navigate to a broken URL to preview the 404 page.Code language: JavaScript (javascript)Frequently Asked Questions
The format for the FAQ is as follows:
== Frequently Asked Questions ==
= Is Launch With Words Free? =
Of course. You can <a href="https://bridgetwillard.com/launch-with-words/">download a free Content Pack</a> to get you started. Additional (premium) Content Packs will be available soon.Code language: HTML, XML (xml)It has the standard section for the FAQ, followed by the question and then the answer. You can add multiple FAQ items.
Screenshots
Your plugin, in my opinion, should have screenshots. It’s a very quick way for a user to determine if they want to use your plugin or not.
For example:
== Screenshots ==
1. Home screen
2. Import tab
3. Imported PostsEach number corresponds to a screenshot you have in your SVN assets folder.
So for 1, you would have in your assets folder a file named: screenshot-1.png. The second screenshot would be screenshot-2.png and so on.
You can use gifs, pngs, and jpegs for the screenshot extensions.
An example of using animated gifs for screenshots can be found in my plugin Simple Comment Editing.
Even simple plugins should also have screenshots. Be creative. You need something there.
Changelog
This section is super important. PLEASE have a changelog. My personal goal is to have the last three releases in the changelog section and then link off to my docs or GitHub releases section.
An example:
== Changelog ==
= 2.7.1 =
* Released 2021-07-02
* Added in a filter for better IP tracking when editing a comment. Props <a href="https://wordpress.org/support/users/tim-reeves/">Tim Reeves</a> for the fix.
= 2.7.0 =
* Released 2021-06-03
* New option: timer can now be compact (e.g., 41:15).
* New option: button themes.
* Using new comment check function name if it exists.
* Correcting typo in admin options.
* Basic styling for edit buttons.Code language: PHP (php)Changelogs are crucial for maintenance teams and users to be able to quickly tell why to update, if there are any breaking changes, and if it is safe to update.
For a super-long changelog, please view the one from my plugin Simple Comment Editing.
Please, pretty please, have a changelog for your WordPress plugin. It helps maintaners and developers quickly see whether to update/install your plugin.
Upgrade Notice
You just need one item here: what’s the latest version of your plugin, and what has changed since the last update.
You can’t use markup here, and the upgrade notice shows in the updates screen in WordPress. Also, everything should be on the same line.
Here’s an example:
= 3.5.1 =
Added two new themes: circular, and circular glass. Fixed SVG bug on the front-end where it could cause extra space at the bottom of a theme.Code language: JavaScript (javascript)That’s basically it for your readme.
For further readme optimization, consider hiring a copywriter and also check out Plugin Rank. Also, check out the Readme documentation.
Further reading:
Gather your assets
When you get SVN access to your plugin, you will have an assets folder.
You want to make your plugin look pretty to others, right?
On your .org plugin page, you can customize the header and the icon to further customize and brand your plugin.
As of this writing, the sizes are:
- banner-1544×500.png
- banner-772×250.png
- icon-256×256.png
- icon-128×128.png
In the example above, I used a .png extension, but they can be jpegs or gifs as well (you can mix and match extensions). Note the use of the banner and icon prefix.
The banner is for your plugin banner (it’ll be used everywhere). Think of it as a cover for a book you’re writing. Try your best to immediately catch the user’s attention.
The icon will also be shown throughout the directory and on the WordPress plugin’s screen. The icon is your branding shrunk down in a 256x256px square. Good luck 🙂
Banners and images are good for branding, but if you take it overboard with a spinning icon gif, you will face blowback.
When creating the banners and images, make sure you:
- Are not violating any trademarks
- Have a license to use the image or graphic (typically an extended license is required)
- Have nothing offensive or a graphic that violates .org guidelines
As a sidebar, I did once get a pulldown request for a banner image I had. I got it from a Creative Commons search. It still violated the license. So be careful here.
As a reminder, the banner and icon images will go into the assets folder in SVN.
Tips & Tricks After Launch
This next section will go over some tips on what to do after launch.
Receiving support request notifications
Once your plugin is submitted, it’s easy to lose track of all the incoming support requests. The best way I’ve found is to simply subscribe to the plugin’s support forum. You’ll receive an email for each support topic and reply. You can use email filters to organize per plugin.
To do this, log into the WordPress Plugin Directory and head to one of your plugins. Click on the Support tab as shown above.
On the sidebar is an area where you can subscribe via email to your own plugin, as shown in the screenshot below.
Simply click “Subscribe to this plugin” and you’ll start receiving email notifications of each forum thread from now on.
Handling plugin support
Support for your free plugin in the WordPress Plugin Directory is expected. In fact, I’m of the mindset that if you don’t plan on supporting your plugin, you shouldn’t list it.
Whether it is commercial or free software, the goal is to have users — is it really software if no one is using it? They are the lifeblood of every project. Ultimately, developers who want people to use their code must answer to those who would.
Justin Tadlock – WPTavern
A long list of unresolved support threads for your plugin indicates:
- That it has a lot of bugs.
- You won’t get any support if needed.
- You can’t trust it enough to install on a site.
The less support you offer, the less chance of getting those coveted star ratings. In fact, it might have the opposite effect of angering users to the point of leaving nasty reviews. And a poorly reviewed plugin will no doubt scare users away from the plugin.
“But Ronald, my plugin is free and I can’t afford to provide free plugin support.”
I totally understand. But it’s the price of admission.
Routinely audit your support requests. Mark anything resolved as resolved. Mark threads as “Not a support request” if it’s commentary or a feature request. Mark old threads as resolved with a note to the user to open the thread back up if they still have the issue.
Dealing with bad ratings
Ratings are arguably the worst part of being a plugin author. You have no control over them.
Did you get a bad rating because you took too long to reply to a support request? Perhaps you didn’t implement a feature a user wanted? Sorry, you’re stuck with it.
Do your best to try to not take it personally. As with a customer service job, just smile, and kill them with kindness.
It is not your job to please that “one” user. So breathe, take a walk perhaps, and come back and address it responsibly.
If you do happen to address the issue later, you can always reply to the rating, @ the user, and ask them to reconsider. It’s worked for me a lot of times.
For example, I white-screened some sites with a plugin release. It was a major oops. I received several bad ratings, but responded to each one and provided a semi-quick fix. The users changed their ratings after the fix due to my proactiveness.
Getting positive ratings
The user of your plugin has a .org account if they are leaving a support request. Sometimes the user created a .org account specifically to leave that request.
Do you know what else requires a .org account? Leaving a rating.
The best way to get ratings is to ask. And what better way to ask than at the conclusion of a support ticket.
To get star ratings on your plugin, you have to ask for them. The best way is through support.
Keep in mind you can’t coerce or pay any users to leave ratings. That’ll get you quickly delisted from .org. However, a simple phrase you can use is: “I’m happy this topic is settled. If you have time, I’d really be thankful for a rating.”
I strive for good ratings and a decent track record on support threads. Support might be a chore and done on a voluntary basis, but I’ve found that it makes your plugin a lot more trustworthy if someone is searching for a plugin.
Ratings are nice because they’ll give the perception that the plugin you’re searching for is a winner. Which leads to more downloads. Which leads to more ratings.
Add a pinned support topic
I recommend pinning a topic to the top of your support forum. Just write a regular topic, mark it as not a support request, and pin it.
Try not to be spammy or else the moderators will get in touch with you.
I’ve used the pinned topics to:
- Alert users of a security issue
- Link to plugin documentation
- Link to any available add-ons
- Answer common questions
You must be logged in and browsing a topic to pin a topic. You’ll see a Topic Admin on the support thread.
Here’s what it’ll look like to users.
Translating your plugin
Translations, also known as internationalization, is a complex topic and I could not do the topic justice in the context of this article.
Instead, I will provide you with some resources.
Marketing your plugin
When marketing your plugin, I recommend the following:
- Have a way for people to contact you about your plugin
- Write tutorials regarding your plugin
- Have a landing page you can direct people to
- Link to related documentation, landing page, and topics in your readme.txt
- Have a professional plugin banner/icon
- Proofread everything (and then proofread again)
Marketing is an immense topic, especially if you plan to have a freemium business model for the plugin.
For expert marketing advice, I recommend Bridget Willard’s book on plugin marketing (Amazon link, non-affiliate).
Miscelleanous Tips and Tricks
Now let’s dive into some miscelleanous tips. I will be update this section as time goes on.
Everyone gets nervous for each release
Releasing an update is hard, especially if you have a lot of users of your plugin. In this case, being nervous is a good thing.
You will not catch every bug, but you’ve done your best. So release it already.
Also, don’t launch on Fridays unless you want to work (or your support team work) over the weekend.
Don’t release on Friday unless you hate weekends.
You don’t have to do a new release every time WordPress updates
So your plugin has been in the directory for a while. WordPress inevitably releases a new version. Now you must update your plugin’s readme to show that it’s compatible with the latest WordPress version.
If you don’t update your plugin’s compatibility version, it’ll get a nice warning advising users that your plugin hasn’t been updated in a while. Additionally, when users try to install or update your plugin, they will get a notice that your plugin hasn’t been tested with the latest WordPress.
If you are serious about your plugin, ensure you keep WordPress version compatibility up to date.
Here’s a common scenario. You’ve created a plugin and it’s fairly solid. There’s no reason for a new release, but you need to show your users that you are compatible with the latest version of WordPress.
The solution is to check out your plugin’s latest tag. If you are not using tags, you can just checkout trunk instead.
You have to use SVN to checkout and make changes to your plugin. I personally use Versions for SVN on my mac to do the heavy lifting (SVN and I do not get along). A good SVN client I’ve heard about for Windows is TortoiseSVN.
The first step is to checkout your tag.
After you checkout the tag, you’ll have a local working copy. Next, you’d find your plugin’s readme.txt file.
Finally, edit your readme with the updated WordPress version number.
Once you’ve updated, you’ll need to do a SVN commit.
And once committed, check your plugin on .org.
Congratulations! You’ve just updated your compatibility without having to release a new update.
The WordPress Plugin team is available to help you
If you have a burning question, the plugin team is there to guide you in the right direction. They can tell you what you can’t do, can do, or even provide assistance if there is a security issue.
If you’re polite, you’ll receive a polite response in my experience. I’ve lost count on how many times I’ve contacted them, and they were super helpful every single time.
If your plugin is rejected (e.g., for insecure code, trademark issues), the plugin team will provide feedback as to why the plugin is rejected.
This is not a time to take things personally or stalk the plugin team members on Twitter. You have to remember that WordPress is super popular and has tens of thousands of plugins, which means the plugin team must do due diligence when approving plugins. Of further note, the plugin review process is done by volunteers. So be nice.
I recommend reading the plugin guidelines before contacting the plugin team.
If you need a fairly quick response, you can join the WordPress Slack and find help that way (it’s much quicker than email).
You can email the plugins team at plugins @ wordpress.org.
Conclusion
Congrats, you made it to the end!
There are many things I didn’t cover just for the sake of sanity and word count. I truly hope this article helped you in some way.
If you have any questions, please leave a comment (you can edit or remove your comment after posting).
You can also reach me on Twitter (@mediaronllc), where I’ll do my best to answer any questions. My DM’s are open.
Finally, if you need to get ahold of me via email for typos, corrections, or even just to chat, please email me at ronald@mediaron.com. I also have a groovy contact form.
Comments are most welcome
Related Posts:
Like this tutorial? There's more like it. Subscribe today!
Ronald Huereca founded DLX Plugins in 2022 with the goal of providing deluxe plugins available for download. Find out more about DLX Plugins, check out some tutorials, and check out our plugins.