Clarification of Guideline 8 – Executable Code and Installs

Since Jetpack announced it installs themes, a number of people have asked if this is a violation of the 8th guideline:

The plugin may not send executable code via third-party systems.

And in specific, these two items:

  • Serving updates or otherwise installing plugins, themes, or add-ons from servers other than’s
  • Installing premium versions of the same plugin

The short answer is no, it’s not, and yes, you could do this too.

The longer answer involves understanding the intent of this guideline, which initially was to prevent nefarious developers from using your installs as a botnet. In addition, it’s used to disallow plugins that exist only to install products from other locations, without actually being of use themselves (ie. marketplace only plugins). Finally it’s there to prevent someone silly from making a plugin that installs a collection of ‘cool plugins’ they found from GitHub and want to make easier to install. Which actually did happen once.

Plugins are expected to do ‘something’ to your site. A plugin that exists only to check a license and install a product, while incredibly useful, is not something we currently allow as a standalone product. This is why we allow plugins to have the in-situ code for updates that is used by their add-on plugins. The plugin we host has to use to update itself.

In addition, we do permit valid services to perform actions of installations onto sites, and have for a very long time. ManageWP, for example, has had this ability for quite a while. It provides a valid service, letting you manage multiple sites from their dashboard, and yes, install and update plugins. Going back to the example of a plugin that hosts the update code for it’s addons, the ‘service’ is the license you bought for the add-on plugin.

The trick here, and this is what is about to sound like hair splitting, is that it’s not the plugin UI on your site that does the install. In order for Manage WP and Jetpack to work, you have to go to your panel on their sites and install the items. If you wanted to make, say, and let people log in, authenticate their sites, and from that interface use a JSON API to trigger an install, you absolutely, 100%, totally can.

To hit the major talking points:

  • Is Jetpack allowed to do this? Yes.
  • Are you allowed to do this? Yes.
  • Can you have your plugin install things? No.
  • Can your service install things onto a connected site? Yes.
  • Are you allowed to have a marketplace plugin? Not at this time.

I know this is frustrating to a lot of people. The reason it never came up before is no one asked us, and it isn’t our place to run your business or invent all the cool things. The guidelines are guidelines, and not laws or rules, to allow people to interpret them, and you’re always welcome to ask us if something’s okay or not. Or warn us if you’re about to do something you think might get the masses up in a dander.


Beware Your Zips!

Its not you, it’s Google.

A lot of people have been mentioning that Gmail won’t send emails if they have zips. Other people have no problem. And reading the list of filetypes that are blocked, it took me a while to figure out what was going on. Not only does Gmail block bad attachments, they also check in your zips to see what files are there:

Certain file types (listed below), including their compressed form (like .gz or .bz2 files) or when found within archives (like .zip or .tgz files)

And guess what filetype Gmail just added on as a banned attachment? `.js` files. Explains perfectly why some of you had no problem and others have massive ones, right? Right.

My advice is, and has been for quite a while now, to use GitHub or Gitlab or Bitbucket or some sort of true development version control system. They all generate their own zips and you can just link us to them. Plus if it’s really complicated to explain what’s wrong, we can highlight the code for you.

I strongly recommend you NOT use free download sources like mega file and all those other ones, especially if they offer faster downloads for money. The majority come with scam popups, viruses, and x-rated ads. Of which I have seen enough. Dropbox is free and has public links. Plus you all have your own websites and can upload a zip there if needed.


Handling Bad Reviews

In general, the Plugin Review team is not the go-to recourse for bad reviews.  Instead, we have a totally brilliant forum support team! There’s some overlap of jurisdiction of course, and some of us are on both teams, but the point here is you should go to the right group to get the right help.

I’m also going to put this out there. You will get a bad review. Most of the time, it will not be deleted. So before you get any further in this post, know that the way you chose to respond, in public, to a 1-star review of your plugin is your own choice.

Our goal with the repository is to have a good place for users to get plugins that fulfill their needs. The reviews are an extension of that, and should viewed as a way for users to educate other users on their experiences. Also a review is about an experience. If someone’s experience with your product is poor, that doesn’t make their review invalid. And to go back to that previous statement, the way you react to those poor experiences is going to impact your reputation, and that of your plugin, a heck of a lot more than that review.

Now, that said, we have a few ‘common’ types of problems with reviews. This post is going to help you handle them and explain when you should call for help, as well as from whom. Later on we’ll be adding it to our documentation, once it’s refined as best we can make it. Please remember, we do not want to make a ‘rule’ for everything. That just invites people to play rules-lawyers and tip over everyone’s cornflakes.

Here’s how you do it and when and why.

First off… How to add a tag!

99.999999% of the time, you’re going to be adding ‘tags’ to posts. This is so easy, you may kick yourself for missing it. On a post, look on the right hand side, under About this Topic and you’ll see a section for Tags

Tags are listed on the right hand side of a post

This is a free-form field where you can add any tag you want. Anyone can add any tag. The forum moderators have an easy way to know who added what, though, so keep in mind we do monitor that. If you want to add a tag to a post and reply, add the tag, press the Add button, and THEN come back to reply. It works better.

Tag abuse (that is calling moderators needlessly) is not okay. Be smart. Be thoughtful. Remember that every last member of the forum and plugin teams is a volunteer. We’re not being paid by Automattic to do this.

The spam review

This is easy. Don’t reply, just add the tag modlook to the post and walk away. The forum team will delete it. If you think it may not be obvious spam, add the tag spam as well.

The sockpuppet review

When a person (or group of persons) makes multiple accounts with the sole intention of leaving reviews on their own plugins (or leaving poor reviews on their competitors), this is called being a Sock Puppet.

This behavior is expressly NOT welcome on the WordPress Forums as it is spamming. But it comes in two flavors:

  1. Someone 5-star spamming their own plugin
  2. Someone 1-star spamming their competition

Both are bad behavior. Both will get plugins removed from the repository and a stern email from us. If you’re doing this, stop right away. Contact your team and tell them ‘Don’t do this!’ Also keep in mind, asking everyone in your company to 5-star review your own plugins is gauche. I mean, really. You’re stacking the deck on purpose and that’s not beneficial to anyone.

Again, do not reply! Add the tag modlook AND sockpuppet to the post and walk away.

The attack/troll review

These are the worst. When someone attacks you and the review seems like all it exists for is to make you feel terrible, you’re going to have to take a deep breath and walk away. An attack is a troll, regardless of how the original poster (OP) feels, they’ve basically been a troll. They’re writing something they know will make you mad and hurt and angry, and they’re doing it on purpose. That’s a troll. And you shouldn’t feed the trolls. You won’t win, and you’ll just make yourself look bad.

Again, do not reply! Add the tag modlook to the post and walk away. These are usually pretty self evident after all.

The review that should have been a support post

This includes the sub-genre “People who submit 1-star reviews in order to emotionally blackmail you for support.”

We all get them.

  1. Reply with a link to the support section of your plugin (or directions on how to get support, or even a note that you don’t provide free support) and remind them that next time, they should ask for help before reviewing.
  2. See if you can fix the problem, but give it no more or less priority than you would any other support request.
  3. If you can solve it, ask them to modify their review. If they go back to and scroll to the bottom, they can edit their reviews!

You’ll notice we’re not telling you to tag the post? Right now we can’t move a review into the support forums and vice versa, so there’s really no point. The forum moderators won’t do anything about it except say “Well, that does suck.” If we could move them, we would, but right now we technically don’t have that ability.

The review about your premium/pro version

If you upsell your plugin’s pro version in the free one, and someone leaves a bad review because the pro version they bought, on the basis of your free one, is bad, congratulations. The review stays. You opened the door with your upsell, encouraging them to do this, and that experience reflects on your plugin as a whole.

If you do not upsell, and there’s no direct link between the free and pro version, or the plugin having the issue is a premium only add-on, tag it modlook and someone will come take a look.

The review about someone else’s plugin

This one can be fixed! Reply and let them know it’s not your plugin, it’s the other one, and then tag it modlook and then use the tag wrongplugin (all one word) to let the mods know what’s going on.

But I really need a plugin moderator!

Okay. So you think you’re an exception? Use the tag pluginmod and a plugin admin will come take a look. Be prepared, though, as we generally will perform a full review on your plugin and any and all guideline violations will result in your plugin being removed until you fix them. Including using too many tags.

#guidelines, #support

Please do not submit frameworks

Note: We are aware that some frameworks are current in the repository. We are asking you not submit any NEW at this time.

This isn’t a new ‘rule.’ It’s not a secret one either. It’s not listed in the guidelines specifically because any attempt to lay down each and every reason a plugin shouldn’t be in the repository just ends in people rule-lawyering. Should we have to tell people “Don’t ask users to write to your plugin files”? No. That should be self-evident. A plugin gets replaced when it’s upgraded, so writing to plugin files means the changes get destroyed. And in many ways, that’s our problem here.

The issue is as follows: Having a framework as a plugin is a poor experience for the user. Not the developer. The user. The user understands “I have an add-on for WooCommerce, I probably need Woo.” They do not always understand “I have plugin Slider Joe. Why do I need Advanced Custom Fields?” In addition, by having a library as a plugin, the onus of version compatibility is now on the person least likely to understand it: the user.

The plugin repository is not, currently, a library or framework repository. It’s not meant like the NPM package manager, or even Composer as a way to define what a plugin ‘needs’ in the same ways for a developer to build a project. The plugin repository is, plain and simple, meant for plugins that users will find useful. Plugins that add functionality to WordPress in a directly inter-actable way.

We don’t allow people to add javascript or fonts on their own to the repository and, I suspect, most of you would nod and say “Well of course not. A font and javascript should be included in the plugin or theme!” We feel the same way about most full blown library and framework plugins too. The user doesn’t need to know or care about the libraries. They shouldn’t be expected to be responsible for it.

At this time, we are not accepting frameworks as we don’t feel frameworks, boilerplates, and libraries are appropriate for the Plugins Directory. We require that plugins be useful in and of themselves (even if only being a portal to an external service). And while there are many benefits to frameworks and libraries, without plugin dependency support in core or the directory, it becomes another level of hassle for users.

The parade of likely support issues:

  • Not recognizing the framework plugin, and thus deleting it (causing the plugin(s) to break)
  • Not recognizing the framework plugin and thinking they’ve been hacked
  • Debugging drama, when we tell them to disable all their plugins and they find its a library problem
  • Updating the framework plugin separately from the dependent plugins, possibly leading to breakage
  • Updating a dependent plugin without updating the framework, possibly leading to breakage
  • Plugins not keeping up with library changes to the point that they break
  • Different plugins requiring different versions of the framework

And bearing in mind that the framework and plugin developers are different people, that’s another level of coordination/compatibility issues. A developer is (in theory) clever enough to write their plugin in a way that it includes the version of the library they need in a way that will not break everyone else. Of course, you developers know that’s a goal and not an absolute.

Frameworks and libraries should be packaged with each plugin (hopefully in a way that doesn’t conflict with other plugins using the framework or libraries). At least until core supports plugin dependencies.

Making this messier is the fact that once a library is in the repository, you shouldn’t put it in your plugin anymore. Why not? Well what happens if they install a library as a plugin, while having the library inside a plugin already? Which one takes precedent? What happens when they’re out of sync and so on? See the goal up above that isn’t an absolute. It gets even messier.

A library is a library, and should be in the plugin, not separate.

Maybe one day we’ll have proper plugin dependencies, but we simply are not there yet.

#directory, #reminder, #repository

Last December we added header images to the…

Last December, we added header images to the top of plugin screens. Since then, we’ve made more changes to the plugin directory and started supporting HiDPI images for those plugin headers as well.

As part of that original header update, one thing that was added which I always meant to do more with was the addition of a new “assets” directory at the top level of the plugin SVNs. This is an optional directory that sits alongside the /tags and /trunk directories, and was just used to hold the banner images. Creating a place to put plugin assets which didn’t need to be included in the plugin itself simply made sense to me.

It also never made sense to me that the plugin screenshots, which are rarely used by the plugin, needed to be included in the plugin’s ZIP file. Some plugins can use these themselves, certainly, but the majority don’t and it’s just really inflating the size of the plugin to include them.

So, starting today, you can put your screenshot files in the assets directory instead of in the main plugin directory.

A few notes, for the technically minded:

  • Screenshot naming conventions have not changed, nor have the readme.txt requirements for their captioning. The naming and behavior is exactly the same, the file can just go into a new place.
  • The old way still works too. If you have your screenshots in the plugin’s “stable” directory, then it will find them there just fine.
  • Screenshots in the assets directory take precedence over screenshots in the plugin’s directory. If you have both, then the assets directory wins. Of course, there’s really no reason to have both, this is just for backwards compatibility.
  • Like everything else in the assets directory, we are serving them through a separate static caching system, and so it may take a few minutes to update when you change them. What this means is that when you put the screenshots in there for the very first time, they may not show up on your page for a few minutes and you’ll just see the captions with no images above them. Please give the proxy some time to retrieve your screenshots and cache them before telling me it’s buggy. It should only take a few minutes. 🙂

The ultimate goal, of course, is to reduce the size of the plugin ZIP files being served. By not including the screenshots in the plugin, files are smaller and upgrades are thus speedier for everybody.

In the future, if we have a need for more “directory only” files, I expect them all to be in the assets directory as well, for just this sort of reason.

Plugin Guideline Change

With the advent of the new directory being on the horizon, which allows us to easily hard-limit the number of plugin tags displayed, we have taken the time to change the guidelines.

While minor updates to the guidelines (with regard to spelling, grammar, etc) are common, major changes are rare and we are striving to be more transparent about them. Hence this post 🙂

Guideline 12 (readme links) clarified to cover spam and tags.

The guideline now reads as follows:

12. Public facing pages on (readmes) may not spam.

Public facing pages, including readmes and translation files, may not be used to spam. Spammy behavior includes (but is not limited to) unnecessary affiliate links, tags to competitors plugins, use of over 12 tags total, blackhat SEO, and keyword stuffing.

Links to directly required products, such as themes or other plugins required for the plugin’s use, are permitted within moderation. Similarly, related products may be used in tags but not competitors. If a plugin is a WooCommerce extension, it may use the tag ‘woocommerce.’ However if the plugin is an alternative to Akismet, it may not use that term as a tag. Repetitive use of a tag or specific term is considered to be keyword stuffing, and is not permitted.

Write your readmes for people, not bots.

In all cases, affiliate links must be disclosed and must directly link to the affiliate service, not a redirect or cloaked URL.

The previous version had the title of “… may not contain “sponsored” or “affiliate” links or third party advertisements” which was too specific and yet not direct enough as to what the intent was. We sincerely mean “Do not use your readme to spam.” Tag abuse, keyword stuffing, and blackhat SEO practices are all spamming.

While we still ask you to use no more than 12 tags, once we move to the new directory, we will simply not display the overage. You should clean that up now. The code is such that there will not be a way to grant exceptions. This is by intent. You don’t need 30 tags, folks.

Guideline 13 (formerly number of tags) now references using included libraries

Since we no longer needed a separate guideline for tags, we have completely changed this guideline to address an issue of security.

13. The plugin should make use of WordPress’ default libraries.

WordPress includes a number of useful libraries, such as jQuery, Atom Lib, SimplePie, PHPMailer, PHPass, and more. For security and stability reasons, plugins may not include those libraries in their own code, but instead must use the versions of those libraries packaged with WordPress.

For a list of all javascript libraries included in WordPress, please review Default Scripts Included and Registered by WordPress.

This issue has become incredibly important when you consider that roughly 90 plugins had to be contacted and closed regarding the use of PHPMailer. They had included the entire library and not kept it updated. I’m aware that we use a forked version of that specific library and I have raised core trac ticket #39714 to address this issue.

While we do not (yet) have a public page to list all 3rd party libraries, I’ve raised meta trac ticket #2431 to hopefully get this sanely documented.


[Somewhat Resolved] Assets/Readmes not showing properly on Plugin Pages

1624 UTC – Tue 19 April

This is MOSTLY resolved, but basically we’re going to be facing sync issues for a while until someone sorts out why they’re getting so behind. The best thing to do here is to WAIT and not push anything. The more you push, the longer the queue gets and slower it gets :/

1541 UTC – Wed 13 April

We are aware of an issue where your assets (banners etc) and readme information isn’t loading properly, and we are looking into it.

Please DO NOT push your code multiple times! It’s like ringing a doorbell over and over. It doesn’t actually make things work better 😉

As a general reminder, though, please try to keep your readme to under 10k. You can shuffle your changelog off to a separate file (chaneglog.txt) to keep things smaller. After all, no one really reads the 1.x version of your changelog from 6 years ago.

In addition, if your plugin is very large, it’s okay to remove old versions from SVN. That will ensure processing and syncing is faster 🙂

We will update this post with any information as we determine exactly what’s wrong.

Update 1: One of the servers is running behind again. So please just be patient. Go for a run. Dance. Sing. It’ll catch up 🙂

Update 2: Still running slow. There are moments where this will work fine, and then it will drag. Sorry.

Want to Close Your Plugins? Email!

Hi everyone, it’s winter at last, and there’s snow in the mountains! This is the perfect time to sit by the fire and look at your plugins and get rid of the ones you don’t want to be on the hook for any more.

Did you make a plugin for an event that happened a long time ago, like the 2008 Olympics? Did you make a featured plugin that got wrapped into core and you’re done?

Email with a link to the plugin and we’ll close it for you!

Doing this means you won’t get any new people complaining about how the plugin doesn’t work and disables itself in WP 4.3 and up (even though you documented it…). It’s less work for you and it’s okay to EoL plugins. We’ll close ’em for you and you’ll be done.

A lovely winter present for everyone.

(If you think the plugin has a use and life, but you don’t want to support it anymore, consider adding the tag ‘adopt me’ to your readme. Just update your readme file with that and maybe someone will come and offer a new home for your old plugin. Check out to see the plugins out there looking for you!)


Plugin licensing: GPLv3 is now accepted

Cross-posted from the main development blog:

The plugin directory’s licensing guidelines have been updated. The guidelines will now allow code that is licensed under (or compatible with) version 3 of the GPL.

The guidelines still encourage use of “GPLv2 or later,” the same license as WordPress. However, we understand that many open source libraries use other licenses that are nonetheless compatible, such as GPLv2 only, GPLv3, and Apache 2.0.

Now may be a good time for plugin authors to review their plugins to ensure a license is specified. You can add License and License URI headers to readme.txt and the plugin’s headers. (You may also wish to include a copying permission statement.) For example:

License: GPLv2 or later
License URI:

You can see this used in the sample readme.txt.

This change brings the guidelines in line with the themes directory, which has for some time accepted GPLv3-compatible code. (Probably a good time to note that Creative Commons licenses are still incompatible with the GPL, and the theme and plugin directories.)


WordCamp US/2016 Recap

First of all I suck for not getting everyone’s names. I’m lucky I remember mine…

This marks my first year as the rep of the Plugin Directory Team and we’ve made some phenomenal headway. We’ve re-written the detailed plugin guidelines to be more understandable and clear for everyone. We’ve actually written a handbook! We never had one before. And Team Apollo has been brilliant getting the new directory from a pipe dream to a beta test reality. Thank you everyone for getting us here.

At WordCamp US 2016 Contributor Day, we had over 20 people going over the brand new Handbook, which lead to the creation of the Glossary and a lot of edits! So a huge thank you to everyone who was here. I really appreciate it. We also had a few people reviewing plugins as practice for the first time. I look forward to their results. Good luck, folks!

Right now the new directory is in public beta. That means if you go check it out you’ll see the brave new world for plugins, and we hope you can help us test things out. If you find bugs in search, please report them on Meta Trac #1692-meta.

The Plugin Developer Documentation has been updated to address the changes (mostly to your Plugin Assets) and the Handbook was written with this new interface in mind.

Which leads us to the eternal question… when will the directory open up to new reviewers?

I’ve said it before and I’ll say it again, the opening of the plugin team to new members will happen after the new directory is complete. This is just a technical necessity. The current system works but it has serious limitations that are just prohibitive to adding more people. That made writing a handbook for a process that doesn’t exist rather interesting. My goal is, once the directory is live, to iron out the how-to-review and then get some experienced developers in to review but not approve, to see if we can come up with a process closer to the Theme Review Team, but not fall to backlog.

This will take a lot of experimentation and patience.

Hang in there.