Add the initial Block Plugin guidelines. #68
Conversation
…s an early draft and are open for comment.
|
|
||
| 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.
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?
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.
|
These all sound good to me :) |
|
|
||
| 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.
blocks.md
Outdated
| 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. Containly only blocks (typically one). |
There was a problem hiding this comment.
The (typically one) statement here conflicts with the earlier statement:
...that is to say plugins that contain only a single independent block
and then later:
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.
So I think I grasp that the guidelines are attempting to make it clear that a Block Plugin may only contain one independent block with the exception of that block containing other blocks as inner blocks. However, I still found it a bit difficult parsing that intent from what is written (and may have even parsed it wrong 😄 ).
A suggestion: All references regarding number of blocks should be explicit about the plugin only having one independent block and then centralize the exception in one statement/place in the doc.
With that in mind, this specific statement would be changed to "Contain only one block".
There was a problem hiding this comment.
Good point, thanks for the feedback! I've been trying to straddle a line here. Really what I'm getting at is that block plugins should be single purpose. Generally that means a single block, but there will be cases where a single purpose requires several blocks (such as the list/item example). It's hard to be precise without second-guessing what kinds of blocks and plugins people will submit. We could try to codify that as something like "irreducible single-purpose block sets" but that seems needlessly technical.
I think what we need is to reword "single independent block" in the first statement. "typically a single block" is one way. "a single block or small set of dependent blocks" is another. I'll think on it some more.
Props nerrad for `Containly`. See #68 (comment)
|
FWIW I think this is going to have to be a separate page than the primary guidelines, otherwise it'll be way too long and confusing. Any suggestions about how to handle that? |
|
|
||
| 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.
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.
People will vote with their feet if a block is overly promotional.
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.
We don't want them discovering their dashboard is full of notices and promos long after they've used the block
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?
|
|
||
| <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. |
There was a problem hiding this comment.
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.
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.
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.
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.
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.
Rapid fire idea: Is there any value in having an integrations category in the block.json?
There was a problem hiding this comment.
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.
Our Block Plugins are built to offer users complete control over the block's properties, using the Editor. For content, as described in the guidelines, we're using either the area below a block (eg. strings of text) or the Media Library. If we're not allowed to create a dashboard for the blocks, then:
The donation link doesn't work, because this is not a donation. I'm trying to understand since SaaS is permitted, where exactly should we make upgrading available for end-users. Thanks! [EDIT] Wanted to point out this work-around for global data: It might be useful for blocks to have a WP menu where this kind of thing can be configured visually instead. |
|
@widgeticdev It sounds like you got a little confused. These guidelines are for block only plugins, which currently cannot be SaSS. You can do everything you described and be listed as a normal plugin, but you cannot do all that and be listed in the block only directory. Also we recommend you have a settings page dedicated to your plugin for letting people enter their API keys. That should not happen in the block sidebar. |
I think what is confusing is the naming. What I see as "a block" is anything using the Gutenberg Editor, regardless if it's listed in the Block Directory or not (for it being SaaS). It also feels like the plugin directory is becoming a second class citizen, even if the majority of blocks will be submitted there, due to developers being able to make a living off their work. About the API Keys, I was looking at this block (see the second screenshot): |
And that is 100% correct.
That is not true, but I understand the feeling. To clarify for you, these are additional guidelines for plugins that wish to be included in the block installer you see on WP 5.5. In order to show up there and be available to be installed while in the new block-based editor, you have to follow additional guidelines. No one is saying you cannot have API keys or a service at all, we're saying you can't if you want to be in THAT specific installer. A 'block directory' plugin contains only a single block that is 100% self-contained with no external dependencies. |
It makes sense, thanks! |
These are the early draft guidelines for Block Plugins for the purpose of the Block Directory.
This PR is intended to serve as an area to review and reference the draft.
Disclaimer: I didn't write these, they're not necessarily the final set of guidelines, and wording may not fully convey the intended intentions.
edit: The guidelines can be easier viewed in blocks.md