Proposal to Modify Plugin Guidelines

This post is a proposal of changes to be made to the PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the Plugin Directory or can be cost-based plugin from a third-party Guidelines.

The majority of changes are intended to address significant issues faced by ESL (English as a Second Language) developers. This proposal also contains a significant rewrite to the lamented 11th Guideline (hijacking the admin dashboard).

This proposal will remain open until after WordCampWordCamp WordCamps are casual, locally-organized conferences covering everything related to WordPress. They're one of the places where the WordPress community comes together to teach one another what they’ve learned throughout the year and share the joy. Learn more. EU 2019, at which point it will be closed and either re-proposed (if there are significant changes), implemented, or scrapped.

The rest of this post will go over an overview of intent, the proposed changes (with summary), and information as to how to contribute. All community members are welcome to participate.


In working with ESL developers, it was mentioned that a number of confusion points were due to the semantics of translations. With that in mind, we have made a series of grammatical clarifications and sentence tightenings. The initial purpose was not to eliminate loopholes, but to make it more clear to someone who is not a native English speaker that certain things are not okay.

During that work, it came to light that guideline 11 (don’t spam the admin dashboard) was in need of overhaul. The overall intent of the goal was not well understood, and within-guideline changes were being criticized heavily to the detriment of the community at large. To that end, guideline 11 received a significant rewrite.

Our overall goal with the 11th guideline was to balance the needs of users to be able to actually use the admin dashboard while permitting needed notifications. The discord arises when these notifications are split between what is needed and what is wanted. Do users need to know about add-ons? In some cases, yes.

While it would be nice to say “We’ll know [spam] when we see it,” that is neither helpful to the developer community nor is it maintainable by any number of volunteers at scale. A guideline that cannot be managed is as worthless as no guideline at all.

This necessitated us changing our goal. We now intend to grant developers a limited but reasonable space to notify the appropriate users of needed and related features (including products and add-ons) while allowing all users the freedom and ability to maintain agency over their own website.

Because a site can have many plugins, allowing all plugins to put multiple ads on multiple pages can quickly make the Dashboard look like a Las Vegas roadside. Our understanding is that a cluttered and unmanageable Dashboard upsets users, making it harder for them to do what they want. This behavior, if enacted by all plugins, could cause WordPress irreparable harm.

In order to achieve that, the following changes have been proposed:

  • Admin messages and advertisements must be limited to one per common page.
  • Messages must only be shown to people who can action on them. For example, don’t show ‘install X!’ to a user who can’t install anything.
  • All messages must be permanently dismissible by an action on a page (such as clicking a dismiss button or an X to close). Filters are insufficient, as not all users are capable of implementing them.
  • No repeatable messages. If a user has been asked to “Try this add-on!” and said no, their choice must be respected. (nb. exceptions will be granted for reminders to complete setup, or if they action in a way that would require that add-on.)
  • All ‘advertisement’ type messages have to directly relate to the developer or the plugin. Ads for other things a developer happens to like aren’t permitted.

What this proposal will not cover:

  • Injecting into search results.
    We already said ads have to be dismissible, so that would be in effect. We are choosing to defer to tracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub. #46763 for the rest but reserve the right to revisit this later.
  • Spamming a plugin’s own settings pages.
    If a plugin wants to make their own admin pages unusable and spammy, they’re permitted to do so. Negative reviews left by users regarding this will not be removed, however.
  • Violations of existing guidelines.
    We already said no tracking users and so on, so that doesn’t need to be repeated.
  • Covering every possible loophole in detail.
    While that is laudable, it’s impossible and would make the guidelines incomprehensible. Also in the past it’s led to people playing ‘rules lawyer’ to get away with behavior.

Proposed Changes

The changes can be seen here:


  • Intro: ‘are expected to’ -> must. You must follow the guidelines.
  • 01: “or later” added for completeness regarding the GPLGPL GPL is an acronym for GNU Public License. It is the standard license WordPress uses for Open Source licensing The GPL is a ‘copyleft’ license This means that derivative work can only be distributed under the same license terms. This is in distinction to permissive free software licenses, of which the BSD license and the MIT License are widely used examples..
  • 02: Removing redundant parenthetical. Remove ‘sole’ as that is misunderstood in some languages to mean it’s their only responsibility, instead of ‘its your own responsibility.’ Correcting bad grammar.
  • 03: Declaring that not using hosting isn’t allowed (i.e. we will close your plugin). Clarify that anyone can dev where they want, but only what we host is what users get.
  • 05: Remove parenthetical in favor of a complete sentence.
  • 06: Due to GDPR we require ToS/Privacy. Remove unneeded reiteration. Clarify that installation via storefronts are also prohibited.
  • 07: Due to GDPR we require ToS/Privacy. Emphasis on prohibited.
  • 08: Formatting fixes and changing ‘servers’ to ‘locations’ due to specific actions by a bad actor. Bad grammar and run on sentences.
  • 09: Formatting and grammar. Clarifying compliance.
  • 10: Removing extraneous words. Breaking apart paragraphs for readability.
  • 11: Major Rewrite to limit abuse of WordPress dashboard notifications and messaging.
  • 12. Break out the list into something more visual, specifically target ads and promotions on the read. Try to be less pejorative overall.
  • 14: Breaking apart sentences and paragraphs for readability. Removing pejorative for ‘trashTrash Trash in WordPress is like the Recycle Bin on your PC or Trash in your Macintosh computer. Users with the proper permission level (administrators and editors) have the ability to delete a post, page, and/or comments. When you delete the item, it is moved to the trash folder where it will remain for 30 days.’ commits.
  • 16: Removing parenthetical.
  • 17: Grammar.


Everyone is welcome and encouraged to comment on this proposal. You may comment in this post, reply on the Github Pull Request, or create a new issue as you see fit.

We ask that if you choose to partake in this process, that you behave with kindness to all involved. This is doubtless a hotly contested topic and tempers will flare. Abusive comments, personal attacks, or accusations of impropriety will be moderated.

  1. Assume good intentions.
  2. Don’t attack the idea or the person.
  3. Be mindful of everyone’s concerns.
  4. Treat others how you would like to be treated.
#guidelines, #proposal