Dev Notes for WP 5.5

[ellatrix]

https://github.com/WordPress/gutenberg/issues?q=label%3A%22Needs+Dev+Note%22

These are all the PRs that need Dev Notes to be written for. Let's write them, share them here as comments, see what is related, and create make/core posts accordingly. Please let me know if you're unable to write a note for our PR. The notes should be posted before WP 5.5 RC, but the sooner, the better.

@youknowriad

• Block patterns: https://make.wordpress.org/core/2020/07/16/block-patterns-in-wordpress-5-5/
• Remove the old block preview implementation Remove the old block preview implementation #21096

@aduth (These need to be taken over, cc @WordPress/gutenberg-core.)

• Block API: Allow block registration without category Block API: Allow block registration without category #22280
• Block Editor: Change default URLInput autoFocus to false Block Editor: Change default URLInput autoFocus to false #19973
• Blocks: Update default block categories Blocks: Update default block categories #19279

@gziolo

• Block API: Add new utility to register block types from metadata in PHP Block API: Add new utility to register block types from metadata in PHP #20794

@nerrad

• Convert _experimentalCreateInterpolateElement to a stable api Convert _experimentalCreateInterpolateElement to a stable api. #20699: https://make.wordpress.org/core/2020/07/17/introducing-createinterpolateelement/

@tellthemachines

• Resizable editor experiment Resizable editor experiment #19082: https://make.wordpress.org/core/2020/08/04/new-editor-preview-options/

Unmarked

• Block API: Add Block Context support Block API: Add Block Context support #21467 (see https://github.com/WordPress/gutenberg/blob/master/docs/designers-developers/developers/block-api/block-context.md)
• REST API endpoints: https://make.wordpress.org/core/2020/07/16/new-and-modified-rest-api-endpoints-in-wordpress-5-5/
• Block Tools: https://make.wordpress.org/core/2020/07/27/new-block-tools-on-wordpress-5-5/
• Image Editing: https://make.wordpress.org/core/2020/07/20/editing-images-in-the-block-editor/

[youknowriad]

There's a few of these that are still experimental, in that case, we shouldn't write a dev note for them but leave the label for later when the API is made stable.

[gziolo]

Block API: Add new utility to register block types from metadata in PHP #20794

As part of that, we should also update https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md and move to the final location.

[nerrad]

What's the deadline for the Dev notes to be written? I can write one for createInterpolateElement but knowing the deadline will help me plan when I write it.

[youknowriad]

@nerrad Something like a month (before RC) but the sooner, the better :).

[gziolo]

There are some issues reported about “Enqueue assets for rendered blocks only” (#22754) and it feels like we should revert it. If we don’t find a working solution for all cases on Monday, we should postpone it to WP 5.6.

[ellatrix]

@gziolo Are we depending on it for anything? If not, perhaps better to be safe and revert? It seems quite tricky.

[gziolo]

#22754 was reverted with #23708 and moved to WordPress 5.6 in the corresponding core ticket.

[tellthemachines]

Here's a dev note draft for the resizable editor/new preview options:

New editor preview options

You can now preview editor content in different screen sizes. Replacing the old preview button there is now a dropdown with “Desktop”, “Tablet” and “Mobile” sizes, as well as the previous front end preview option.

The new preview options currently only work on medium to large screens (>= 600px). In the future, there may be a way to preview large screens on a phone.

Block developers

If you’re a block developer and would like to have responsive styles for your blocks in the editor, use the #start-resizable-editor-section and#end-resizable-editor-section markers to define responsive styles. Styles between these markers will be picked up by the editor and render correctly when it is resized. As an example, this is what your styles would look like:

#start-resizable-editor-section {
    display: none;
}

/* add all responsive styles here */

#end-resizable-editor-section {
    display: none;
}

Currently, we aren’t able to manipulate theme editor styles because they are loaded inline in a <style> tag, instead of a separate stylesheet.

Other uses

The media query-manipulating hook, useSimulatedMediaQuery, takes a string to be used as a marker, so it can be used in other contexts, with different makers, for different styles.

Discussion around further features can be found in #19082

[noisysocks]

Block API: Add Block Context support #21467 (see https://github.com/WordPress/gutenberg/blob/master/docs/designers-developers/developers/block-api/block-context.md)

I came here to write a dev note for block context, but I don't think I can do better than what @aduth wrote in the documentation that's linked there, so I suggest we just use that! 🙂

[gziolo]

Blocks: Update default block categories

@aduth shared a proposed dev note for a new list of block categories in #19279 (comment):

Block API: Allow block registration without category

The Block category is no longer mandatory or doesn't have to match an existing category slug during block's registration. When that happens then a block is rendered in the inserter under the Uncategorized section.

[gziolo]

Block API: Add new utility to register block types from metadata in PHP #20794

I opened PR #23832 that convert Block Registration RFC into a documentation page for Block Metadata that should serve as a source for dev note (it might need some refinements):

https://github.com/WordPress/gutenberg/blob/c5d28282538838aefa37a2a7c570dbfd4b00fff4/docs/designers-developers/developers/block-api/block-metadata.md

[TimothyBJacobs]

Dev notes have been drafted for all the REST API changes. Most related to Gutenberg is https://make.wordpress.org/core/?p=82418&preview=true

[nerrad]

Dev notes are drafted for createInterpolateElement: https://make.wordpress.org/core/?p=82449&preview=1&_ppp=0942283df4

If there are no suggested edits by Friday, I'll publish then.

[youknowriad]

I think we should write a dev note about the new opt-in features for blocks: line-height, padding comes to my mind but maybe there are other block tools I'm missing. cc @ellatrix @ItsJonQ

[ItsJonQ]

@youknowriad At the moment, line-height is opt-out. I'll make an update to make it opt-in, to be more consistent with the recent properties like spacing or link colour

[oandregal]

@ellatrix I've removed the "needs dev note" from #22722 as this still requires the plugin to work and it won't be ported to 5.5 (see). Going to edit the issue description to remove it from here as well.

[ellatrix]

@tellthemachines What other APIs are introduced apart from useSimulatedMediaQuery? Could these APIs be marked unstable, considering that we're looking at using iframes instead to preview the content?

[youknowriad]

I'm going to remove Update the theme colors to rely on CSS variables #23048 for now. I'm working on bringing this setup to Core more globally for 5.6. So I think it's better to wait for this one.

[youknowriad]

I'm also removing the ones about the color support flag as it's still experimental.

[mkaz]

Is there an Image Editing dev note? @youknowriad raised in #23966 to attach the method to disable (that PR also needs to be back-ported to WP 5.5). If a dev note is started the description at the top of the PR can be included for disabling.

[diegohaz]

#23316 will not be part of 5.5 release (I guess). Do dev notes still make sense in this case?

[youknowriad]

@diegohaz I guess it was added just to make sure we don't forget. For now, it seems better to leave it for the next WP release.

[tellthemachines]

@tellthemachines What other APIs are introduced apart from useSimulatedMediaQuery? Could these APIs be marked unstable, considering that we're looking at using iframes instead to preview the content?

We have getPreviewDeviceType and setPreviewDeviceType in the block-editor store, but wouldn't these be unchanged with the iframe solution?

We also have useResizeCanvas in the edit-post package. That's used to check that the current screen size isn't bigger than the size we want to resize to, and also to check if the screen itself gets resized at any point. Not sure this would be considered API as it's more of an implementation detail, and would have to change anyway if/when we implement emulation of large sizes on small screens.

Should we mark useSimulatedMediaQuery unstable? As that is definitely specific to this implementation. And in that case, should it be mentioned in the dev notes at all?

[ellatrix]

I think we should mark useSimulatedMediaQuery unstable.

[tellthemachines]

I think we should mark useSimulatedMediaQuery unstable.

Done: #24279 . Does it still require a dev note?

[aduth]

I noticed that the URLInput autoFocus default prop value was announced as a change pending in WordPress 5.5, but the associated pull request #19973 was never merged. I don't think it's going to be part of 5.5?

I'm having a hard time recalling what was preventing #19973 from being merged, aside from fighting with the test suite.

[youknowriad]

Oh! what a mistake; I updated the post and removed that section for now. Thanks for catching that @aduth

[ellatrix]

This looks complete. Thanks everyone!