Block guideline updates

[tellyworth]

Some proposed updates, still WIP.

[lukecarbis]

Is this the right place to discuss these updates?

Block Plugins must not include code that displays alerts, dashboard notifications, or similar obtrusive messages unrelated to the purpose of the block.

I hate ads as much as the next guy, but ads in traditional WordPress plugins are not only permitted, they're built into the business models that allow for such an active and dynamic plugin ecosystem.

I'm concerned that by disallowing advertisements, the growth of the Block Directory would be adversley impacted.

Further points for consideration:

similar obtrusive messages

What about unobtrusive "messages"? Is the intent is to allow for a grey area in which the block plugin reviewers can make judgement calls? (Not a criticism – this could be helpful – but it makes it hard for plugin authors to plan a Freemium model when they're at the mercy of the reviewer).

unrelated to the purpose of the block

This is vague. Does it allow for adding "greyed out" (inaccessible) premium features to free blocks? Should it?

[Ipstenu]

I'm concerned that by disallowing advertisements, the growth of the Block Directory would be adversley impacted.

Serious ask here, where would a block ONLY plugin put an ad?

Remember we're talking about block-only plugins here, not regular plugins with a bunch of features. The only place I can think of is in the block-sidebar, which would be disallowed with a regular plugin so why would it be allowed here?

[lukecarbis]

Personally, I can't think of a subtle place to put an ad – but I've learned not to underestimate the creativeness of advertisers.

I can imagine a "notification" style ad… or one that appears inside the block preview.

Okay… so this is a bit of a tangent – but I've seen blocks in the past (can't remember which) that show an alert in the preview area informing the user that the block requires additional configuration. Imagine a PayPal button block that needs you to add your PayPal email for it to work properly. The notification could say "this block isn't yet configured". Another example is the "placeholder" in an image block prior to adding an image. This sort of design precedent could easily give way to messaging like "Huge savings at Yoast! Black Friday Sale".

The only place I can think of is in the block-sidebar, which would be disallowed with a regular plugin

Serious question:
Imagine a block that had 3 "styles" available in Free, and an additional 3 in Pro. Could the free version of that block show a dropdown list containing all 6 styles, but 3 were greyed out, with a "helpful" notice saying something like "more styles available with Block Pro"?

Is that an ad? I've definitely seen that done.

Just trying to see where the limits are. I'm coming from a position of a user who hates ads in the admin, as well as a Product guy who understands the need for their careful, unobtrusive use. I've written about my ideas for what should and shouldn't be allowed.

[Ipstenu]

Okay… so this is a bit of a tangent – but I've seen blocks in the past (can't remember which) that show an alert in the preview area informing the user that the block requires additional configuration. Imagine a PayPal button block that needs you to add your PayPal email for it to work properly. The notification could say "this block isn't yet configured".

Those would not be permitted by default in the Block only directory. And I'm stressing this for a reason :) If your plugin is not just install-and-go, if it requires additional configurations, then it's not applicable at this time for the block directory. You can be in the regular directory, not the block-only sub-directory.

That restriction is covered in the 6th guideline:

Block Plugins are intended to work seamlessly and instantly when installed from the editor. That means they should not encumber the user with additional steps or prerequisites such as installing another plugin or theme, signing up for an account, or logging in or manually connecting to an external service.

I think we're okay there :)

Another example is the "placeholder" in an image block prior to adding an image. This sort of design precedent could easily give way to messaging like "Huge savings at Yoast! Black Friday Sale".

That's actually disallowed overall by the Directory Guidelines today. So no. That's not allowed, block directory or not. Messing with a user's interactions like that is not okay.

Imagine a block that had 3 "styles" available in Free, and an additional 3 in Pro. Could the free version of that block show a dropdown list containing all 6 styles, but 3 were greyed out, with a "helpful" notice saying something like "more styles available with Block Pro"?

That would be an ad (in this case an Upsell, which is an advertisement of other features). But more over, it goes against the bottom line goal here, which is: The Block Directory is for block only plugins that work the second they're installed. They just work. And if you're making them not-work for whatever reason (registration, premium features etc) then you're not a good candidate for the Block Directory. That doesn't mean you can't host your code on .org, just that you can't host it in the Block Directory.

[lukecarbis]

Great elaborations and explanations @Ipstenu. Thank you!

I'm hearing that right now, for those thinking about creating a Freemium offering that is block-based, it's best to include that in the Plugin directory, not the Block directory. The reason is that the Block Directory should contain simple, straight-forward, no-fuss blocks that just work as soon as they're added.

Perhaps including further explanation about not seeing advertisements or upsells in the "User Expectations" section of this document might be useful? Additionally, in the "Developer Expectations", I'd suggest making it clear that these guidelines are intentionally stricter than the Plugin Directory guidelines, and it's still possible to submit Block plugins there.

[tellyworth]

I'm hearing that right now, for those thinking about creating a Freemium offering that is block-based, it's best to include that in the Plugin directory, not the Block directory. The reason is that the Block Directory should contain simple, straight-forward, no-fuss blocks that just work as soon as they're added.

Yes you're exactly right on the intention and reasoning.

I don't speak for the plugin review team, but I would note one point here. There is a path forward for commercial developers to work with the Block Directory, which is spelled out in section 5: a Block Plugin can interact with other WordPress plugins, provided the block is still useful without it and the other rules are followed. So a block in the Block Directory could indeed load additional styles or trigger extra functionality from a commercial plugin or theme if it's available on the site. It'll have to abide by the rules about not requiring or upselling that plugin or theme though. I'll defer to @Ipstenu on exactly what constitutes an upsell ad, but I would think that a discreet note in the description that the block is compatible with / works with Plugin X seems like it might be reasonable(?)

Perhaps including further explanation about not seeing advertisements or upsells in the "User Expectations" section of this document might be useful? Additionally, in the "Developer Expectations", I'd suggest making it clear that these guidelines are intentionally stricter than the Plugin Directory guidelines, and it's still possible to submit Block plugins there.

Thanks for the suggestions! I've added some more clarifying language to the Expectations sections, does that help?

[lukecarbis]

@tellyworth Yes, that language works really well, especially the "Developer Expectations" section. Thank you.

[jeffpaul]

With WordPress 5.5 getting released today and the Block Directory officially being a part of core, is there an ETA on getting these guidelines finalized, published, and distributed for developers to utilize as a reference? Happy to help with any needed copy reviews or testing against existing blocks for questions/concerns/etc.

[tellyworth]

is there an ETA on getting these guidelines finalized, published, and distributed for developers to utilize as a reference?

The guidelines are published here: https://developer.wordpress.org/plugins/wordpress-org/block-specific-plugin-guidelines/