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

2015 Community Summit And How You Can Help the Plugin Team

Sadly, many of the same reasons we could not add new members to the Plugin Team last year are still an issue (see 2014 Community Summit Wrapup). The codebase has been improved, but the process is slow. Just to give you some hope, the work done on the Theme Repo is being used to help us. So. Soon. Soon. We’re restructuring the backend to make it more clear as to who can do what, but most things are waiting on the re-vamp.

The only real ‘news’ is that we’ve been sneakily moving our documentation over to https://developer.wordpress.org/plugins/wordpress-org/ – Please check it out to keep up with all the information about what makes good plugins in the repo. Oh, and we’ve swapped reps. I’ll be taking over as the plugin team rep and that really changes… nothing at all. @boone did a great job and I thank him for it.

You Can Help

While we are still stuck on the old system, you can jump in and help us by emailing plugins@wordpress.org when you find people playing fast and loose with the rules.

We encourage and welcome updates from everyone, but please don’t be snippy. Be serious. If someone has powered by links, or is phoning home, yes, please let us know. But don’t let your personal feelings get in the way. This is a big deal. A lot of people send us reports from a place of anger. Don’t be that person. That person makes it harder for us to figure out if someone has a personal vendetta against a plugin and/or developer, or a legit concern. We’re all passionate, but remember to channel that passion into something beneficial.

How to Report Issues

If you’ve found a plugin _doing_it_wrong(), email plugins@wordpress.org and remember:

  1. Make your subject clear. (“XSS Vulnerability in Hello Derpy” or “Derpack Developer swearing at users in forums” are good)
  2. Always provide an exact link to the plugin.
  3. Report plugins with guideline violations.
  4. Report developers who are behaving badly.
  5. Be detailed. If you know what file and line of code is the problem, tell us.
  6. Provide examples of vulnerabilities. If you already know what’s hackable, show us. It makes it faster for us to verify and reproduce. Link to forum threads etc etc.

Remember: We don’t retroactively enforce guideline changes unless there is a legal, copyright, or security related reason. For example, we no longer allow new plugins to call wp-load.php directly, however we don’t hunt around for plugins that do so. If a plugin is closed for using a non-GPL library and, in the review, we note other best-practices violations, we will require them all to be fixed before reopening.

Also, we won’t be following up with you as to what happened most of the time. We’d love to. We can’t and keep up with emails. Please don’t take it personally. As we add more people to the team we may be able to change that, but right now it takes us away from validating security issues.

 

Tools

Rami asked “What do you guys even use to check plugins and look for bad things?” and the real answer is “Our eyes.” We don’t have a theme-check type plugin because there are very few ‘standard’ things to look for (possibly it could check for license issues, including jquery files, and calling wp-load directly sort of things).

Remember: Thou Art Mortal

And so are we.

We’re people too. We make mistakes. We miss things. We have bad days. We get sick. We have families. If we don’t reply to you super fast, please sit on your hands and give us five days. Five. You should get some sort of reply from us within five, even if it’s ‘we’re still talking about this, sorry but it’ll take a while.’ Sending us an enough every 12 hours (yes, someone did that) is annoying.

Hunting us down on Twitter and Slack because we didn’t reply right away is similarly uncool and harassing. We use the email so that everyone on the team can read the conversations. Don’t take it off-line. Keep it in the email and that way, if you’re talking to Otto and he goes to a BBQ fest for two weeks days without access, Pippin can pick up the conversation and help you out.

Just be patient and calm. Especially if we’ve just closed your plugin. We know that sucks, and we totally get you’re angry sometimes. Just try to remember we’re all humans and treat us with respect like fellow humans.

Grumpy Otto (is there another kind?) looking at the camera.

Take the plugin. Leave the cannoli.

#guidelines, #repository, #team-reps

Guidelines for Plugins that Include Company and/or Product Names in the Plugin Name

When submitting plugins to the WordPress.org repository, there are a number of guidelines for what is and is not acceptable. One of those guidelines has to do with the name of your plugin, especially when it includes the name of a company, trademark, or product.

If you have submitted a plugin and received a rejection email that started with something like the quote below, it means you need to adjust the name of your plugin.

We’re no longer accepting plugins that include a trademarked product name or term as the name or slug of a plugin. Nor are we accepting plugins that include the name of another plugin at the beginning of the name/slug.

Before you submit your plugin for review, take the name of your plugin into consideration and try and pick a name that will not be rejected. To help you choose a better name, here are a few guidelines to keep in mind.

Your plugin includes the name of a company, trademark, or product

Take WooCommerce as an example.

The following names will be rejected:

  • WooCommerce – Product Add Ons
  • WooCommerce – Better Stats

We will, however, accept the following (if not already taken):

  • Product Add Ons for WooCommerce
  • Better Stats in WooCommerce

One of the key points is that your plugin’s name cannot start with the company/trademark/product name.

Here’s another example. Stripe Payments will be rejected. Payment Form for Stripe will be accepted (if available).

You work for the company whose product’s name you are using

You are permitted to submit plugins that include the company/trademark/product name If you work for the company owns it.

For example, if you work for PayPal, you may submit a plugin named PayPal Payments.

In order to have your plugin approved, you must submit the plugin from an official company account. This usually means the email address on the account is {yourname}@{company}.com If you submit it from a non-company account, your plugin will be rejected.

You do not work for the company but you have permission to use the company/product/trademark in your plugin’s name

In this case, we will ask you for proof of written permission from the company that explicitly states you have permission to use the name.

For example, if you wish to submit a plugin called Gravity Forms – CSV Exporter, you must have proof of written permission from Rocket Genius, Inc. to include Gravity Forms in the name.

Please provide proof with your initial submission, otherwise it will be rejected.

Questions, Feedback, Comments

If any of this is unclear or you have comments or questions, feel free to leave them below.

Update 1

There was some confusion as to some of the guidelines regarding trademarks, company names, and product names.

To help clarify:

1. If your plugin name includes a trademarked product name or term, you must be the owner of that trademark, work for the company that owns the trademark, or you must have permission from the owner to use it.

2. If your plugin’s name includes the name of a company or the name of a company’s product, you may not use their name at the beginning of the plugin’s slug. “WooCommerce – Product Addons” is not permitted. “Product Addons for WooCommerce” is permitted.

3. These guidelines are specifically at the slug of the plugin (wordpress.org/plugins/this-is-your-slug). The slug is auto generated based on the name you enter when submitting your plugin. After submission, you can still alter the exact name that is displayed on your plugin’s page via the readme.txt file.

Note: these are not 100% hard-fast rules and there are always exceptions. It is up to the reviewer’s discretion how strongly they wish to enforce these guidelines. To best ensure your plugin is approved in a timely manner, however, do your best to follow these guidelines.

#guidelines, #policy, #submissions

Plugin Submission ZIP files

This comes up now and then so I thought we should have a quick post about what your plugin zip should be when you submit.

Keep in mind, if we email you and tell you we cannot download or open your zip, please don’t just say “Well it works for me!” The fact is, we’re smart people. If we cannot get the zip to open, there actually is a problem. Check the link and check the zip. Attach the zip to your email reply.

It should be a zip file

I know, that’s obvious, but we actually force you to send a zip for a number of reasons. I strongly urge you NOT to use anything fancy like winrar to compress it, because that can make your zip un-openable on Mac or Linux boxes. Protip? We all use Mac or Linux.

Use a real URL

Don’t use localhost. Don’t use your dev environment. Don’t try to upload the zip. It’s a link to where your zip is publicly accessible. No more, no less.

Be very careful when you use ‘free’ upload sites. If they open up a dozen popups, we’re not going to risk them. We don’t like viruses.

Speaking of…

The link should be one that’s accessible to NON-logged in users

Bitbucket folks, this means you, eh? If you’re using GitHub, you can link us to the zip they make UNLESS you’re including submodules. Surprise! Github’s autogenerated zips don’t include that. Drives me nuts. I know.

Test the URL in an incognito window, just to be sure. It takes a second and you’ll see exactly what we see.

The zip should be only the plugin

It should be exactly what you would upload manually to WordPress to test (which you did test, right?) because that’s what we are going to do! Don’t include themes or other zips or required plugins. All of those requirements should be accounted for in your plugin by making checks and properly informing users as to what they need to do.

By the way, please don’t nest your zips. Seriously. We see a lot of zips that have a readme.txt and then a second zip file. That means we have to open the zip, extract the other zip, check that it’s right, and then upload it.

#guidelines, #submissions