Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add the initial Block Plugin guidelines. #68

Open
wants to merge 2 commits into
base: master
from
Open

Add the initial Block Plugin guidelines. #68

wants to merge 2 commits into from

Conversation

@dd32
Copy link
Member

dd32 commented Nov 21, 2019

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

Copy link
Member

felixarntz left a comment

These rules make sense to me, restricting to a single block and no further UI is great and will result in less bloat and better UX.

There's one point I would like us to revisit.


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.

This comment has been minimized.

Copy link
@felixarntz

felixarntz Nov 22, 2019

Member

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".

This comment has been minimized.

Copy link
@0aveRyan

0aveRyan Dec 24, 2019

Member

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.

@pattonwebz

This comment has been minimized.

Copy link
Member

pattonwebz commented Nov 22, 2019

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>

This comment has been minimized.

Copy link
@pattonwebz

pattonwebz Nov 22, 2019

Member

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).

This comment has been minimized.

Copy link
@nerrad

nerrad Nov 23, 2019

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".

This comment has been minimized.

Copy link
@tellyworth

tellyworth Dec 2, 2019

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.

blocks.md Outdated Show resolved Hide resolved
Props nerrad for `Containly`.
See #68 (comment)
@Ipstenu

This comment has been minimized.

Copy link
Collaborator

Ipstenu commented Dec 6, 2019

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>

This comment has been minimized.

Copy link
@ericnicolaas

ericnicolaas Dec 8, 2019

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?

This comment has been minimized.

Copy link
@brianhogg

brianhogg Dec 12, 2019

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.

This comment has been minimized.

Copy link
@bfintal

bfintal Dec 21, 2019

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

This comment has been minimized.

Copy link
@WPMechanic

WPMechanic Jan 9, 2020

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.


<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.

This comment has been minimized.

Copy link
@brianhogg

brianhogg Dec 12, 2019

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.

This comment has been minimized.

Copy link
@maxcady

maxcady Dec 14, 2019

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.

This comment has been minimized.

Copy link
@WPMechanic

WPMechanic Jan 9, 2020

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.

This comment has been minimized.

Copy link
@StevenDufresne

StevenDufresne Jan 14, 2020

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.

This comment has been minimized.

Copy link
@StevenDufresne

StevenDufresne Jan 14, 2020

Rapid fire idea: Is there any value in having an integrations category in the block.json?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.