Guideline Update

The previously proposed changes have been merged into the plugin guidelines.

It’s important to note that I do not think this is a ‘complete’ or ‘finished’ project. The guidelines are imperfect, in part because it’s impossible to create a rule for every single possible variant of a possible conflict, but also because we cannot predict the future.

There are people who are unhappy we didn’t go far enough with certain guidelines — like not saying “you may have 3 links to your own products on your plugin admin pages.” Others are unhappy we’ve gone as far as we did in certain situations — such as the 9th guideline’s prohibition against harassment.

Accepting the imperfection of English, as well as the flaws built in to creating guidelines for such a large audience, many of whom do not speak English natively, has led to situations where we have to settle. These guidelines are not perfect. They are not complete. They will be constantly evolving and adapting as we try to please and protect the majority of developers and users.

I encourage all of you to help us write them better. You can email us at plugins@wordpress.org or make pull requests on the GitHub repository. While we may not accept all requests, I promise we do listen to and read every last one.

#guidelines

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