Plugin Authors: Tips, Tricks, and Guidelines for Navigating WordPress.org

Tips And Tricks Concept On Desktop
License: Adobe Stock

This article is quite long. Here’s a Table of Contents:

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

Screenshot of Ronald Huereca's WordPress profile.
My .org Profile

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.

Plugin Slug Not Found in the WordPress Plugin Directory
Plugin Slug Not Found in the WordPress Plugin Directory

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 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.txt

This 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.

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.

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.

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.

=== 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.html Launch With Words is a product that combines the experience of a small business copywriter with blogging prompts to encourage you to publish a blog post once a month. Simply follow the prompts and publish. Now you are a copywriter! Because blogging shouldn't be hard. == Description == https://www.youtube.com/watch?v=kaDYOr6qpDY Launch With Words is a product that combines the experience of a small business copywriter with blogging prompts. This helps you publish a blog post once a month. No need for boring placeholder text or lorem ipsum in your blog. Simply follow the prompts and publish. Now you are a copywriter! Because blogging shouldn't be hard. <h3>A Value-Add for Developers</h3> Launching a small business website with Launch With Words is an incentive for your client to publish regularly. We all know that publishing regularly is a ranking signal for SEO. Publishing regularly gives your clients an appreciation of the tool you just built. A client who appreciates the site, uses it. In their eyes the website "works." You're hired for Phase II and so on. The goal of this plugin is to help the client with copywriting. It encourages them to publish once a month so their website and generates leads. The website you use is one that works. You've worked hard to launch their site with words, so why not continue that habit? <h3>Do I Need Anything Else?</h3> Yes. Launch With Words is a JSON importer. Head over to <a href="https://bridgetwillard.com/downloads/launch-with-words-starter-content-pack/">the Starter Content Pack</a> to grab that JSON file. Launch With Words installs this JSON file. It is a year's worth of blog post prompts -- as drafts -- to encourage your clients to write and guides them in blogging best practices. Just say no to lorem i-sum, or placeholder text in the blogs. Hello World? No thanks. These prompts are based upon the small business ebook, "If You Don't Mind Your Business, Who Will?" from established copywriter, Bridget Willard. <h3>Features and Tips</h3> <ul> <li>Download the Free Starter Content Pack for <a href="https://bridgetwillard.com/downloads/launch-with-words-starter-content-pack/">Launch With Words</a></li> <li>Encourage your clients to publish monthly.</li> <li>Compatible with the Block Editor.</li> <li>No need for placeholder blog posts.</li> <li>The best websites are ones your clients use.</li> </ul> Install the plugin. Activate it. Import a content pack. Deactivate the plugin. Delete. <h3>German Starter Pack is Also Available</h3> Das deutsche Starter Pack ist verfügbar. <a href="https://bridgetwillard.com/downloads/starter-content-pack-in-german/">Dieser Download</a> enthält die neueste Version des Importers sowie die Prompts json-Datei und den PDF-Willkommensbrief -- in Deutsch. Launch With Words befindet sich auch im Plugin Directory. Sie benötigen noch die <a href="https://bridgetwillard.com/downloads/starter-content-pack-in-german/">json-Importdatei von mir auf meiner Seite</a>. If you have a feature request, <a href="https://github.com/MediaRon/launch-with-words/issues">please add a GitHub issue</a>. Thank you! We would love it if you would take the time to <a href="https://wordpress.org/support/plugin/launch-with-words/reviews/#new-post">Rate the Plugin</a>. Please and thank you. == Installation == 1. Just unzip and upload the "launch-with-words" folder to your '/wp-content/plugins/' directory. 2. Activate the plugin through the 'Plugins' menu in your dashboard. == Frequently Asked Questions == = Is Launch With Words Free? = Of course. To get started, <a href="https://bridgetwillard.com/downloads/launch-with-words-starter-content-pack/">download the free Starter Content Pack</a> with the blog prompts. Premium Content Packs will be available soon on bridgetwillard.com. == Screenshots == 1. Home Screen 2. Import Tab 3. Imported Posts (Free content pack) 4. Imported Posts (Premium content pack) 5. Editing an Imported Launch With Words Content Pack == Changelog == = 1.0.7 = * Released 2022-03-02 * Testing with WordPress 5.9. * Adding redirect to settings upon activation. * Better documentation regarding starter pack. = 1.0.6 = * Released 2021-09-17 * Correcting a few admin links. = 1.0.5 = * Released 2021-09-16 * Updated brand colors. = 1.0.3 = * Released 2021-02-05 * Fixing closing SVG tag in the admin. = 1.0.2 = * Released 2021-01-26 * Documentation Update = 1.0.1 = * Released 2021-01-24 * Initial release on WordPress.org == Upgrade Notice == = 1.0.7 = Testing with WordPress 5.9. Adding redirect to settings upon activation. Better documentation regarding starter pack.
Code language: HTML, XML (xml)

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.html
Code 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/MediaRon
Code 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

WordPress Plugin Screenshots
WordPress Plugin 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 Posts

Each number corresponds to a screenshot you have in your SVN assets folder.

Plugin Screenshots in your SVN assets folder
Plugin Screenshots 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

WordPress Plugin Directory Banners and Icons
WordPress Plugin Directory Banners and Icons

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 🙂

Plugin Banner Image and Icon
Plugin Banner Image and Icon
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:

  1. Are not violating any trademarks
  2. Have a license to use the image or graphic (typically an extended license is required)
  3. 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.

Custom Query Blocks on the WordPress Plugin Directory
Custom Query Blocks on the WordPress Plugin Directory

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.

Subscribe To Your Own Plugin
Subscribe To Your Own Plugin

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.
Ratio of answered to unanswered support threads
Ratio of answered to unanswered support threads

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.

A picture of a WordPress plugin's rating area.
Rating of plugin Highlight and Share
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.

Topic Pinned Topic Sidebar Option
Topic Pinned Topic Sidebar Option

Here’s what it’ll look like to users.

Pinned Topic Example
Pinned Topic Example

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:

  1. Have a way for people to contact you about your plugin
  2. Write tutorials regarding your plugin
  3. Have a landing page you can direct people to
  4. Link to related documentation, landing page, and topics in your readme.txt
  5. Have a professional plugin banner/icon
  6. 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.

Checkout your latest tag
Checkout your latest tag

After you checkout the tag, you’ll have a local working copy. Next, you’d find your plugin’s readme.txt file.

Checked Out Tag Folder
Checked Out Tag Folder

Finally, edit your readme with the updated WordPress version number.

Plugin Readme File
Plugin Readme File

Once you’ve updated, you’ll need to do a SVN commit.

Editing and Committing Your Tag
Editing and Committing Your Tag

And once committed, check your plugin on .org.

Updating WordPress Plugin
Updating WordPress Plugin

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 [email protected] I also have a groovy contact form.

Ronald Huereca
Ronald Huereca

Ronald Huereca

Ronald has been part of the WordPress community since 2006, starting off writing and eventually diving into WordPress plugin development and writing tutorials and opinionated pieces.

No stranger to controversy and opinionated takes on tough topics, Ronald writes honestly when he covers a topic.

3 thoughts on “Plugin Authors: Tips, Tricks, and Guidelines for Navigating WordPress.org”

  1. As a new WordPress plugin developer, my biggest concern is monetization: How do we publish WP plugins as FOSS, with a reasonable freemium model, securing Pro assets, and avoiding getting too ripped off by other developers or clients sharing assets. Thanks!

    Reply
    • If your source is open, you won’t be able to avoid people ripping off your work. GPL allows this and it’s perfectly legal and there’s little you can do to stop it.

      One way around this is to have a hybrid sass model much like some Delicious Brains plugins or EWWW Optimizer.

      On .org, you can’t hide or obscure code based on a license, but you can have features that can only interact with the sass with a valid license.

      Reply

Leave a Comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Ronald Huereca
MediaRon - Ronald Huereca

Ronald created MediaRon in 2011 and has more than fifteen years of releasing free and paid WordPress plugins.