Reviewing the Guidelines – 2017

I do this regularly, but recently I received a comment that the guidelines were still too vague.

I need to stress that this is by intent. If we make guidelines like “You can only have 3 external links” then people will find ways to exploit that. However I do not think that guidelines are perfect. Which is why I’m proposing a minor update to them to address the following concerns:

  • Overall tense of guidelines made consistent
  • Update introduction for readability and unpack what we mean by keeping email updated
  • Explain the converse of 3
  • Put the important part of 5 on top
  • Add link to forum guidelines to 9
  • Add prohibition against harassment to anyone in WP
  • Clarify self-dismissible alerts are acceptable in 11
  • Changed tense of 12 and 13 to emphasize their importance
  • Grammar fix for title of 15
  • Fix reference to zips in 16 (upload now vs link to)
  • Reword title of 17 to explain that PLUGINS must honor…
  • Guideline 18 has received a full rewrite to clarify what rights we reserve and reiterate our promise to do this as fairly as possible.

You can see all the changes proposed here on GitHub

Please read the guidelines and leave comments or pull requests on Github. The plan is to make these live in January 2018 so please jump in and help! Thanks.

#announcement, #guidelines

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 WordPress.org’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 WordPress.org 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, my.servicename.com 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.

#guidelines

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 WordPress.org (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.

#guidelines

Revised Guidelines Are Live

We soft-launched them on the 20th, just to make sure we didn’t mess anything up. Those last few spelling and grammar edits are killer. However yes, the guidelines, reviewed and revised by the community are now the official Plugin Developer Guidelines.

While I can hope they’re easily understood by all, I know that’s a fond wish. I’m leaving the repository on Github open for the time being, in order to allow people who spot late breaking issues to report them. If you do spot problems, please open an issue on the GitHub Repo or email plugins@wordpress.org and let us know.

In addition to just rewriting the guidelines, we took the time to codify the expectations of developers and cost of not abiding by the guidelines, as well as a reminder that we do remove plugins for security issues. We are doing our best to be transparent of what we expect from you and, in return, what you can expect from us.

Finally, THANK YOU. Everyone who helped write this, edit it, and who was patient understanding I was chasing down people to get their sign-off on what might be construed as massive changes, I greatly appreciate the time you spent on this project. It’s a massive undertaking to re-write guidelines in the public eye, in a way that won’t pull the rug out from anyone. Our goal was to clarify, not totally change, but also to address the needs of an ever changing technology.

Our goal, as always, remains to provide a safe place for all WordPress users – from the non-technical to the developer – to download plugins that are consistent with the goals of the WordPress project.

Please take the time to read the Detailed Plugin Guidelines.

#guidelines

Reviewing the Revamped Guidelines

Thank you everyone for being patient about this.

This summer was spent re-writing and editing and tweaking the guidelines. I ripped them down, sat and spelled out what they meant, then I rewrote them to be more clear. Then I got the plugin review team to review the changes. Then I had a group of people at WCNYC Contributor Day review them.

Finally, I moved it all to a GitHub repo and started to ask smaller groups to review it. Then we had a quick rebranding and that all brings us here.

I would like everyone in the community to read these proposed updates to the Plugin Directory Guidelines.

WordPress.org Plugin Guidelines

At the risk of sounding trite, pull requests and issues are welcome.

If you feel a guideline’s explanation is unclear, please create an issue or a pull request with what you feel should be changed and why. All grammar/spelling corrections are greatly welcome. We’re trying to write these for all levels of developers, as well as people who may not speak English proficiently. Using words like ‘obsequious’ should be avoided (nb: That’s mostly to me who uses those words regularly).

All feedback should be opened as issues in the tracker.

Let the games begin!

#directory, #guidelines

Status on the Plugin Repo Revamp, Guidelines, and Handbooks

First off, please read Obenland’s post on the repo:

Plugin Directory v3: Next Steps

Obviously we have a long way to go.

As for the Guidelines, I wanted to be done and ready to release them to everyone before 4.6 dropped, but I’ve been using small focus groups at WordCamps first. This resulted in a lot of small changes that I want to take the time to go over with the Plugin Team before I unleash it to the world for nitpicking. A huge amount of thanks goes to @courtneydawn @logankipp and @lunacodes for being my first run of editors!

As we clean up the aftermath of the 4.6 emails (you have no idea…), I’ll be pinging people whom I know to be good copyeditors and have mentioned wanting to help before. If you think that’s you, please leave a comment here. I won’t be asking everyone as I’ve found that to be overwhelming for me to be able to process, so please don’t take it personally. Once I have it mostly good, I’ll flip it from Google Docs to a Git Repo and people can pull request!

Also a handbook! Oh me oh my I’ve been writing one! And I’m almost ready to ask Sam to flip the switch for it. It’s sparse and will need lots of attention too.

Thank you everyone for understanding the crazy that goes on with all this, and for being patient. It’s been a long 7 months for me working on all this.

#directory, #guidelines, #repository

Reviewing the Guidelines

The official plugin guidelines are currently found on DevHub under Detailed Plugin Guidelines. The older version now redirects (thank you!). Like the Codex and DevHub, we’re mid transition and apologize for any confusion when that redirect wasn’t happening.

Historically, any time someone has a patently clear misunderstanding about what a guideline means, they are asked if they can help us understand what was confusing and how to make it better. I’m sad to tell you that in the history of me asking that question, less than five people out of the hundreds have replied.

Since we have the goal in mind to expand the plugin review team, one of the requirements on me as the rep is to clarify the Plugin Repository Guidelines. In the last seven months (since the Community Summit 2015) I have been refining, tweaking, and editing them in an attempt to make them more clear so we can get them at a point where they will be easily enforceable by people who don’t have the deep history of understanding misbegotten behaviors that caused their creation in the first place.

The sole reason this has been done in private was so that those currently on the team were all on the same page before we bring it up to the rest of the world.  Once we know we understand the guidelines, then we can educate the next generation. It’s taking us this long to straighten things out in part because we don’t have a handbook. Not a one. I’ve started from scratch to make a passable one, which is now being converted into something understandable and sharable with others.

My personal goal is to have ‘beta’ release of the Handbook up by end of July and the revamped guidelines available for public discussion here no later than end of August.

I am greatly sorry if anyone thinks they weren’t listened to, or that the guidelines were some great big secret circle of conspiracy. Neither are the case. We have always listened, we have always been adjusting things, and we’ve (almost always) been working on a major overhaul of everything. We were just starting from a very different position than nearly any team out there on WordPress.org, which made it exceptionally difficult.

There have been a lot of hurt feelings both within the team and without, but I’m optimistic that we’re now, finally, at a good place to move forward.

Please keep an eye on this blog for what’s next.

#guidelines, #teams

Repository Guideline Reminder: Do Not Remote Load Content

In a very irregular feature, we’re posting about various plugin guidelines and what they really mean to you.

This week, we want to remind you about a long-standing guideline in the repository, which is covered in item #7 – Don’t phone home without consent.

No “phoning home” without user’s informed consent. This seemingly simple rule actually covers several different aspects:

The guideline goes on to break down what we mean in four main points:

  1. No unauthorized collection of user data
  2. All images and scripts shown should be part of the plugin
  3. No 3rd party ad tracking
  4. No ad-spam

That second item (which I emphasized) is what we want to remind you of today.

Your images, your scripts, your CSS, etc, should all be included locally. Besides not tracking users, keeping everything locally will make your plugins faster. It obviates the problem of external load. It means when your server is down for maintenance, you didn’t just slow down everyone’s wp-admin. It means you’ll never DDoS yourself on accident.

Unless you’re a service, your plugin has no business phoning home to your own servers to load data. If you are a service, you must have this clear in your readme as to what the service entails, preferably with a link to your ToS and and explanation as to what is tracked. This is for your protection. By remote loading files, you have the ability to track users. Data tracking is a huge deal, and while we understand you want to do it for metrics, it someone was taking your data without permission or consent and selling it or using it to promote their code, you’d be pretty ticked off.

You can (and should) re-read all the guidelines on https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/ – we rarely change them though we may reword things for clarity.

If you have suggestions as to how we can be more clear about #7, please leave a comment and let us know.

Keep in mind, we’re not going to spell out everything to the letter, as in our experience that leads to people playing nit-picky fake-lawyers about everything, and still violating the ultimate rule of the guidelines which is ‘Don’t be a spammer.’ For example, we’re not going to make a rule for not stealing other people’s plugins. You already know stealing is bad, right? 😈

#guidelines, #reminder, #repository

Policy Reminder: Tracking Users

Do not, under any circumstances, track usage of your plugin without explicit consent.

If you want to ask your users if you can track them, by all means ask. But you may not require it, and you shouldn’t make it look like they have to in order to use your plugin. That’s being dishonest.

This has been a guideline for a very long time, it’s not negotiable. Assume people do not want to be tracked and have it to be an opt-in feature.

If your plugin uses Google Analytics, emails you on plugin activation, triggers some complex check on your servers when a plugin is updated, or tracks usage in any other way when a user has not clearly said “Yes, I allow you to track me,” your plugin will be removed from the repository and you will have to correct this in order to get it back.

This extends to ads provided by a third party service. If your plugin includes advertising from a third party service, then it has to default to completely disabled. This is to prevent tracking information from being collected from the user without their consent. Again, this is all about people opting into being tracked.

(For those thinking about using Adsense, don’t. Re-read their Adsense Display Guidelines and note that they do not want you to put ads on non-content pages … which is what the whole WP Dashboard is.)

Don’t assume that just because someone said they agreed to have usage tracked by you that they’re okay with usage tracked by someone else. Don’t be shady or vague. Tell people upfront “This is who will get the following data…”

Remember, user trust is paramount to your plugin’s success. If people find out you’re sneaky tracking them, you will lose that trust in a heartbeat and there’s nothing anyone can do to help you restore it.

#guidelines, #reminder

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 WordPress.org 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 https://wordpress.org/support/view/plugin-reviews/PLUGINNAME 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