Add the initial Block Plugin guidelines. #68
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,80 @@ | ||
| <h2>Guide to submitting plugins to the Block Directory</h2> | ||
|
|
||
| The goal of the Block Directory is to provide a safe place for WordPress users to find and install new blocks. | ||
|
|
||
| <h3>User Expectations</h3> | ||
|
|
||
| * Users will have a place they can go, both within their WordPress admin and on WordPress.org, where they can download and install blocks that have been pre-vetted for major security issues. | ||
| * Users will be able to one-click install blocks from their admin, one at a time. | ||
| * Blocks will appear in their block library after installation and activation. | ||
|
|
||
| <h3>Developer Expectations</h3> | ||
|
|
||
| * Developers will have a concrete set of requirements and guidelines to follow when writing blocks for the Block Directory | ||
|
|
||
| <h3>Definitions</h3> | ||
|
|
||
| First up, some clarity. For the purposes of the Block Directory, we distinguish between two types of plugins: | ||
| 1. Plugins that exist solely to distribute a block. | ||
| 1. All other plugins, including those that bundle many independent blocks, plugins that contain blocks in addition to other functionality, and plugins with no blocks at all. | ||
|
|
||
| These guidelines apply specifically to the first type of plugin, which we’ll call here a Block Plugin. If your plugin is of the second type, then the further guidelines and restrictions do not apply to your work. All plugins, be they block-only or not, are required to comply with the Detailed Plugin Guidelines https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/. | ||
|
|
||
| <h3>Block Plugins and the Block Directory</h3> | ||
|
|
||
| The Block Directory contains only Block Plugins, that is to say plugins that contain only a single independent block and a minimum of supporting code. Block plugins have the following characteristics: | ||
|
|
||
| 1. A specific type of WordPress plugin, with the same structure including a readme.txt file. | ||
| 1. Containing only blocks (typically one). | ||
| 1. Contain a minimum of server-side code. | ||
| 1. Do not have any UI outside of the post editor. | ||
|
|
||
| In addition to following the guidelines that apply to all WordPress plugins, Block Plugins that are submitted to the Block Directory must adhere to these guidelines: | ||
|
|
||
| <h3>Guidelines</h3> | ||
|
|
||
| <h4>1. Block Plugins are for the Block Editor.</h4> | ||
|
|
||
| Your block plugins should contain a block, and a minimum of other supporting code. It should not contain any UX outside of the editor, such as WordPress options or `wp-admin` menus. Server-side code should be kept to a minimum. | ||
|
|
||
| <h4>2. Block Plugins are separate blocks.</h4> | ||
|
|
||
| Block plugins are intended to be single purpose, separate, independent blocks, not bundles or compendiums of many blocks. In most cases, a Block Plugin should contain only one (single) block. It should not contain multiple blocks that could reasonably be split up into separate, independent plugins. | ||
|
|
||
| Block plugins may contain more than one block where a clearly necessary parent/child dependency exists; for example a list block that contains list item blocks. | ||
|
|
||
| <h4>3. Plugin titles should reflect the block title.</h4> | ||
|
|
||
| We want users to interact with blocks, not product names. Block Plugins should be named to reflect the block; for example "Image Grid" block, "Improved Slider", "Business Hours" block. Please avoid plugin names unrelated to the block itself like "Widgets Incorporated Block", and refrain from block names that include trademarks or names that you do not legally represent; for example you cannot name a block "Facerange Block" unless you work for Facerange and have their permission. | ||
|
|
||
| <h4>4. Block Plugins must include a <code>block.json</code> file.</h4> | ||
|
|
||
| The Block Registration RFC outlines the format of a `block.json` file: https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md | ||
|
|
||
| Block Plugins must include a valid `block.json` file. In addition to the requirements specified in the RFC, the `block.json` must include the following attributes: | ||
| * name | ||
| * title | ||
| * At least one of: script, editorScript | ||
| * At least one of: style, editorStyle | ||
|
|
||
| <h4>5. Block Plugins must not require payment or a paid account to function.</h4> | ||
|
|
||
| This includes payment for premium features. You may use the donation link feature. | ||
|
|
||
| <h4>6. Block Plugins should work independently.</h4> | ||
|
|
||
| Block Plugins must not require another plugin in order to function. | ||
|
|
||
| They may use an external/cloud API where necessary, but not if that API requires a paid account for access. | ||
|
There was a problem hiding this comment. I'm mostly on board with this, but this rule would prevent many useful block plugins interfacing with 3P services from being eligible and thus encourage them to go for the traditional plugin route, which would likely result in worse UX. For example, I think a "MailChimp Subscription Form" block plugin makes complete sense to have, even though you have to pay for the service on the other side. Maybe we could loosen this rule, such as: "If that API or service requires a paid account for access, the service name must be included in the plugin and block name." That would easily make it clear to at least many folks. Of course, at the same time, the trademark rule has to remain satisfied, i.e. if the developer does not work for MailChimp, it could be called "Subscription Form for MailChimp". There was a problem hiding this comment. There are also a number of examples of services that include a free tier, but also have paid tiers, both requiring an account/API token. Apple & Google's App Stores include a marker that says "Includes In-App Purchases." Usually this is used where there's a baseline, persistent free functionality and a paid upgrade either removes advertisements or adds additional features. However, there are plenty of services that have a free API tier (Mapbox, Google Maps) that max out at a certain usage threshold. Of course these services can release a standard Plugin to make a Block available, I understand not wanting to be a game-able funnel for paid services to signup new users, but particularly for services that offer a generous but limited free tier I'm not sure this is quite flexible enough. There was a problem hiding this comment. Just a note on Felix's idea, I don't think we can require plugin names to have trademarks (the name of the external service) in them, as the Plugins team already is dealing with companies who want plugins removed that have trademarks of theirs anywhere in the title There was a problem hiding this comment. Take my Charterboat plugin for example. One of the "big wins" I've been working on with industry leaders is innovate a seamless integration for independent Charterboats that rely on bookings through outside travel agents. I've created a series of blocks which will read from the boat's REST API and produce an availability calendar, boat listing, etc by only inputing the domain of the remote Charterboat. This would really benefit the industry as a whole, but I read this rule to say that these blocks could not be admitted to the directory because they require that the boat has installed the premium plugin Charter Boat Bookings Pro in order to have that REST Data available to the block? There was a problem hiding this comment.
Hey Meg, you can still add the plugin to the directory - just not the 'block directory'. Plugins for the block directory are different to other plugins like yours. A 'block directory' plugin contains only a single block (or potentially a collection - but that is still undefined or not well defined in regards to the directory) - compltely self-contained with no external dependancies beyond what is in WordPress. This is so they can be installed on-the-fly as single blocks without need to install anything more. Your plugin contains several blocks with external dependancies so it is more suited for the standard plugin directory :) There was a problem hiding this comment. That will be a repetitive point to make "you can still add the plugin to the directory - just not the 'block directory'." and should be as often in the documentation as possible. |
||
|
|
||
| They should not rely on an external API or cloud service for functions that could be performed locally. | ||
|
|
||
| <h4>7. Server-side code should be kept to a minimum.</h4> | ||
|
|
||
| Since Block Plugins are WordPress plugins, they necessarily contain PHP code for metadata and initialisation. As much as possible, they should avoid including additional PHP code or server-side libraries. The WordPress REST API should be the preferred interface to WordPress, rather than custom server-side code. | ||
|
|
||
| We recognise that there are limits to the REST API, and situations where server-side PHP is the only performant way to implement a feature. In those situations, PHP code may be included. Please ensure that such code is clearly written, used as little as possible, and well documented. | ||
|
|
||
| <h4>8. Must not promote other blocks, plugins, or themes.</h4> | ||
|
There was a problem hiding this comment. Yes to this. I've already encountered (via plugin block bundles) blocks that promote and upsell other block plugins. Usually paid upgrades. I don't want to have those in 1-click installed blocks. There was a problem hiding this comment. How is "promote" defined here? If I have a single-block plugin that's fully functional on its own, but can be enhanced by running it in conjunction with another plugin, is just having that interactivity considered promotional? Imagine Block Plugin X has a tight set of defined features which will be perfectly suitable for most users. However, if you happen to use it alongside Full-Featured Plugin X, you can enhance it with additional features which are directly related to the functional purpose of Block Plugin X. Does having that potential interactivity between Block Plugin X and Full-Featured Plugin X mean that Block Plugin X is not meeting this guideline? Or does it depend on how it's presented to the user? There was a problem hiding this comment. While it makes sense to require the downloaded block itself provide features that don’t need any payment, why would a link in the settings/config of that block to learn more about additional premium features (sales of which can help the developer support the free version) not be allowed similar to existing plugins? For example on the bottom of the block’s settings output? Having guidelines around taking over other parts of the UI or not including any admin notices above the editor would make sense, though. There was a problem hiding this comment. I’m curious about this as well. A link or some other way of promotion to an existing plugin should be allowed. Guidelines around promotion should be added instead of just disallowing all of them. Perhaps adding a uniform note with a link in the block description would work, something like “this block is a part of XYZ blocks” kind of like the donation button There was a problem hiding this comment. Without the ability to create a market around blocks, there will be less blocks. Donations are generally considered to be a non-viable business model and the best way to incentivize more blocks of better quality is to allow for a freemium model in addition to or really replacing the donation link or button. There's an opportunity here to define up-sell channels for potential use in a way that won't disrupt flow, but can still catch the eye of the user should they be curious for more information. Providing a link or button on the bottom of the block settings or even a small link in the description could be enough to get people interested if there's more features available. Nothing flashy, nothing overpowering, but the presence of a link or button would be felt without disrupting flow. If everyone had to play by the same rules (ie. defined elements, placement, etc.) then quality becomes an even more important factor. Without this, the vast majority of people who want to write blocks at a professional level is going to be restricted to developers working either in their spare time for the fun of it or those paid by corporations to help extend their influence. We lose a whole sector of development back into 3rd party marketplaces which are already overflowing with block compilations and bundles, and this entire effort which has serious long-lasting potential for the future of WordPress creation and customization gets stunted. There was a problem hiding this comment. If the goal is to prevent spammy advertisements in the block directory, there should just be very strict guidelines as to what is permitted for promotion instead, and perhaps define what "promote" is. There was a problem hiding this comment.
This is a special case because of the seamless install. You can install a block plugin, use it in your post, and publish your post without ever leaving the editor. A user could do that, perhaps adding several new block plugins, and only visit the main dashboard hours or days later. We don't want them discovering their dashboard is full of notices and promos long after they've used the block, and when there's no clear causal link between installing a particular block and its side effects outside the editor. I expect that the guidelines will be relaxed later. This is a very new thing that's the first big change to the way plugins are installed in core for a long time. One bad actor could easily sour it. Let's try to keep it as simple and safe as possible to start with, and open things up over time as we learn from real experience. There was a problem hiding this comment. Doing that will literally limit us in what we can do and make it almost useless to us. So I’d suggest changing your stance. Also, this feels like you’re the one making the final decision, and that decision has already been made. I object to both. There was a problem hiding this comment.
I think things are being likened to the admin notices area where it's possible for things to get out of hand and have a ton of things floating in there. But I don't think this is what people are pointing out here, nor is it what people want to do. A simple thing like a note in the block's description might suffice for now (visible only on the block that has been installed). Yet, even a small promotion like this isn't allowed.
There was a problem hiding this comment. Like @tellyworth said, this guideline might be relaxed later, but I think this is a good first step for the directory. There was a problem hiding this comment. It's a good first step if the block directory is only intended for simple, layout-based plugins with no database requirement or enhanced functionality. For example the one event block doesn't actually let you pick from events on a calendar or link to a page with more details, but rather type the basic event details in manually. Under this restriction we can't even include the block in s separate plugin with a link to download the plugin used to actually save and manage events. Like any plugin in the WordPress directory some validation needs to be done by the user to ensure it will be useful to them. Why arbitrarily restrict what can be included, and make it harder for the user to find and install what they need, as long as the plugin makes a block available and isn't doing something malicious? |
||
|
|
||
| Block Plugins are blocks. They must not include advertisements, prompts, or promotional messages. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If blocks should be generically named “Image Grid” how would a user differentiate one image grid block from another in the block listing? The differentiation provided by a product name is helpful especially when the functionality provided by the block might not be as straightforward or generic as (say) a slider.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good point. But what about block collections? There are an increasing number of block collections and it is really difficult to find blocks if you can only see numerous "ultimate" block collections.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Once this new selection screen gets off the ground, we may see the collections stall out a little bit and maybe become rarer over time in favor of newer individual blocks. For the moment, it's just the optimal way to be able to get people to download / buy blocks from a developer.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Agreed, a poorly executed block preview would make this problematic. On the other side, this could be addressed with the combination of the plugin's icon, author and credibility. I think if we put more emphasis on the non title bits that legitimize the plugin, we make it much more straightforward in finding the block you are specifically looking for or discovering the right block to build with.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Rapid fire idea: Is there any value in having an
integrationscategory in the block.json?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I agree that block collections have no place in the block directory.
However, if I have for example a charterboat calendar, charterboat listing, and charterboat grid item it makes sense for users to have a way of accessing all of these together. While they do not "require" each other, they are designed to work together and have limited functionality without all 3....
Are we really just relying on the alphabet to bring those up together if a user types in Charterboat? Seems less sophisticated than we could be.