gutenberg

gutenberg copied to clipboard

This is a work in progress.

Tracking all Dev Notes from Gutenberg plugin releases 13.1 - 14.1

After a review of the processes establish during 6.0 release cycle, the release leads for documentation agreed on some modifications. Please read the information below carefully. If you have questions, connect with @bph or @zzap via Slack or comment here.

Not all developer related information needs to be in a separate DevNote on the Make Core blog for the field guide. We can group related information. During the course of the next few weeks, this first list will be completed after the last Gutenberg plugin. We can already make decision on some features if warrant a stand-alone blog post or if the information will be part of a group post.

Stand-alone post

To streamline the process and eliminate bottlenecks, all writers of stand-alone dev notes will receive privileges on the Make Core Blog. (Please connect with @bph or @zzap, if you need access)

• Create your note in a new post,
• Save as Draft
• Enable public preview
• Share the link to the public preview in a comment below, as "ready for review"
• "For dev notes, each one must have at least two reviewers" (Handbook)

Part of a group post

If the information related to your PR will be part of a group post, please write the dev note in a comment on the PR, so it can be reviewed and, if necessary commented on, by the release docs team or a reviewer.

Before you start writing

📣 please read the handbook pages: ⭐️ Writing developer notes ⭐️ Style & Substance section of the Post & Comment Guidelines for Make Blog ⭐️ Documentation Style Guide - Good for reference, when in doubt, especially when English is not your native language. 🗓 Deadline Drafts posted on Make Blog between Beta 1 and Beta 2 (Between September 20 and 27, 2022)

---

• [x] #42729 @fabiankaegy (draft on Google Doc)

Global Styles

• [ ] #44015 @oandregal
• [ ] #44018 @scruffian (if ported back to 14.1)
• [ ] #41689 @scruffian

Layout

• [x] #42544 @andrewserong (partial devnote)
• [x] #41527 @glendaviesnz draft link below
• [ ] #40875 @tellthemachines
• [ ] #42763 @tellthemachines
• [ ] #42085 @tellthemachines

Elements support @scruffian

• [ ] #41981
• [ ] #41822
• [ ] #41659
• [ ] #40260
• [ ] #41140
• [ ] #41786 #43088 @getdave @MaggieCabrera
• [ ] #41753
• [ ]

Fluid typography @ramonjd

• [x] #39529 (Public Preview on Make Core Blog)

Create Block Scaffolding Tool @gziolo / @ryanwelcher

• [ ] #40479
• [ ] #43718
• [ ] #43481
• [ ] #43035
• [ ] #42839
• [ ] #42254
• [ ] #42151
• [ ] #41642
• [ ] #41273
• [ ] #41289
• [ ] #44185

Style Engine @ramonjd @andrewserong

• [ ] #37978
• [ ] #43840
• [ ] #39446
• [ ] #39736
• [ ] #39790
• [ ] #41803
• [ ] #40332
• [ ] #40665

Block Library (Package)

• [ ] #37998 @afragen
• [ ] #40554 @matiasbenedetto / @youknowriad
• [ ] Nav block - new fallback experience @draganescu / @getdave

Query Loop @ntsekouras

• [ ] #43632
• [ ] #40933

Components package

• [x] #43230 @mirka

Margin deprecations @mirka

• [ ] #43436
• [ ] #43867
• [ ] #43870

Popover @ciampo (dev note here

• [x] #43691 @ciampo
• [x] #43845 @ciampo
• [x] #43546 @ciampo
• [x] #43617 @ciampo

New APIs

• [ ] #43590 @sunyatasattva
• [ ] #43268 @adamziel
• [ ] #42430 @gziolo
• [ ] #42258 @gziolo

useDisabled hook + disabled component

• [ ] #40890 @youknowriad
• [ ] #40631 @youknowriad

Deprecated

• [ ] #40502

Unsorted for now

• [ ] #44131
• [ ] #42457
• [x] #41885 - covered under #40875
• [ ] #41605
• [ ] #40680

---

Updates: 9/21 / - bph Added Style Engine PRs delete #41873 per Adams comment below

to be continued

Fluid typography @ramonjd

Thanks @bph! I have a dev note ready to roll, but have shelved it until we're closer to RC1. I am told this is the usual protocol.

@ramonjd and all

Publishing close to RC 1 is not a hard rule. It only makes sure that there isn't something in the dev notes, the might have changed between drafting it and release.

On the doc release team we need a bit of a lead time as Dev Notes need to be reviewed by two people before publishing. If all dev notes are published a day before RC 1, it creates an unnecessary bottleneck and undue stress on the team.

Ideally, the draft on the make blog could be available around Beta 1. Then it can get into the queue for reviewers, finalized and published by RC 1, to make it into the Field Guide.

Thanks for the ping @bph!

• https://github.com/WordPress/gutenberg/pull/42544 @andrewserong

For this one, I don't believe a separate post is required, it can be added to any dev note blog post on smaller changes. I've drafted a comment on the PR for inclusion in such a post: https://github.com/WordPress/gutenberg/pull/42544#issuecomment-1198863716 — the main purpose of the dev note is to communicate to creators of themes that currently use an undocumented approach of opting out of Layout styles to use the new formal approach.

Thank you, @andrewserong - I marked this dev note as done for now.

Thanks @ramonjd for message about the Draft Dev Note ready for review 👏  🙌

Draft for spacing presets available for review at https://make.wordpress.org/core/?p=98177&preview=1&_ppp=00c8d7730a

• #43663

I commented on the above PR because I thought it should be mentioned in the dev note. In my opinion, it is better to include it as part of the group post, such as Block Editor miscellaneous Dev Notes for WordPress 6.0.

Thank you so much @t-hamano to add this here and put this on our radar for WP 6.1.

@bph I created a draft for elements support: https://make.wordpress.org/core/?p=98557

https://github.com/WordPress/gutenberg/pull/42677#issuecomment-1240126502 I have left a comment about "the inheritance of template lock in the column block", as it was deemed necessary to include this as part of the dev note.

@scruffian Thanks for the Dev Note! and the link!

I've listed the authors of #43840 in the issue description. I was listed but I was involved.

👋 - I was wondering if all the additions in the templates offered to create in site editor should be part of post like this already posted one: https://make.wordpress.org/core/2022/07/21/core-editor-improvement-deeper-customization-with-more-template-options/.

Related PRs that Needs Dev Note label was added are:

• https://github.com/WordPress/gutenberg/pull/42457
• https://github.com/WordPress/gutenberg/pull/41189
• https://github.com/WordPress/gutenberg/pull/41387

For Query Loop extensibility PRs, there is going to be a documentation page(related open PR), so I guess that would be enough? 🤔

Finally for the Query Loop parents filter is just a filter for the block to restrict the results based on their parent. I don't think it needs a separate dev note, but if we want we could add somewhere a sentence about it like:

Query Loop has now parent filtering support, with a new property in the existing query attribute, called parents. The filter is only shown for hierarchical post types and if you have selected multiple parents it will display the children of all of them(union).

I started a draft post for Block API changes covering:

• https://github.com/WordPress/gutenberg/pull/42430 / https://core.trac.wordpress.org/ticket/53148
• https://core.trac.wordpress.org/ticket/56408
• https://github.com/WordPress/gutenberg/pull/42258

For the Create Block section, there is also an open PR that we should land closer to the release date that integrates the new render API from block.json and bumps the minimum required WordPress version to 6.1:

• https://github.com/WordPress/gutenberg/pull/44185

Besides, we should mostly cover new CLI options / prompts that allow selecting different variants (dynamic vs static) and a way to scaffold code only for a block (without the plugin wrapper).

@bph I've marked this one as done:

https://github.com/WordPress/gutenberg/pull/41873

It was closed without merging as there wasn't enough alignment to move forward.

• https://github.com/WordPress/gutenberg/pull/40875

I've added a draft note for the layout refactor in this comment (https://github.com/WordPress/gutenberg/pull/40875#issuecomment-1253190670). The layout dev notes will likely all be consolidated with ones from @tellthemachines and @ramonjd into a single blog post, since lots of the individual PRs and changes are all related.

Oh, I think we need to add #42763 (Try "constrained" content width as new layout type) and #42085 (Core CSS support for root padding and alignfull blocks) to this list. I'm writing dev notes for them, anyway 😅

@tellthemachines I updated the tracking section above.

I added a dev note for pseudo class support for elements in theme.json. It's being tech reviewed by @scruffian and @draganescu.

Block Library: Add filter for inner blocks in the Navigation block

I added a short dev note for this.

https://make.wordpress.org/core/?p=98980&preview=1&_ppp=56c57f986f

Hey folks, there's a draft post for all Layout-related dev notes here: https://make.wordpress.org/core/?p=99019&preview=1&_ppp=992173a9ba

I've thrown up a first draft for the Style Engine dev note here:

https://make.wordpress.org/core/?p=99063&preview=1&_ppp=10ef94cb0b

Thank you!

I moved the draft of the block-based template parts devnote from the Google Doc to a draft post: https://make.wordpress.org/core/?p=99068&preview=1&_ppp=25529485e7

Howdy here is the draft dev note for the navigation block fallback updates in 6.1 https://make.wordpress.org/core/?p=99073&preview=1&_ppp=82bfc16fed

Closing the loop for https://github.com/WordPress/gutenberg/pull/44015 and https://github.com/WordPress/gutenberg/pull/44159

Draft at https://make.wordpress.org/core/?p=99398&preview=1&_ppp=40c8cd7718

Filters for theme.json

WordPress 6.1 has introduced some server-side filters to hook into the theme.json data provided at the different data layers:

• theme_json_default: hooks into the default data provided by WordPress
• theme_json_blocks: hooks into the data provided by the blocks
• theme_json_theme: hooks into the data provided by the theme
• theme_json_user: hooks into the data provided by the user

Each filter receives an instance of the WP_Theme_JSON_Data class with the data for the respective layer. To provide new data, the filter callback needs to use the update_with( $new_data ) method, where $new_data is a valid theme.json-like structure. As with any theme.json, the new data needs to declare which version of the theme.json is using, so it can correctly be migrated to the runtime one, should it be different.

Example:

This is how to pass a new color palette for the theme and disable the text color UI:

function filter_theme_json_theme( $theme_json ){
	$new_data = array(
		'version'  => 2,
		'settings' => array(
			'color' => array(
				'text'       => false,
				'palette'    => array( /* New palette */
					array(
						'slug'  => 'foreground',
						'color' => 'black',
						'name'  => __( 'Foreground', 'theme-domain' ),
					),
					array(
						'slug'  => 'background',
						'color' => 'white',
						'name'  => __( 'Background', 'theme-domain' ),
					),
				),
			),
		),
	);

	return $theme_json->update_with( $new_data );
}
add_filter( 'theme_json_theme', 'filter_theme_json_theme' );

I've noticed that in the 6.1 cycle there has been a few features introduced in theme.json. Some I've tracked (there may be more):

• hover/focus/active states
• spacing presets
• fluid typography
• new elements
• filters

I suggest that we create a "theme.json in WordPress 6.1" devnote to compile them all (whether or not some of those individual features merit its own devnote as well).

cc people that led the changes in this area in case anyone wants to draft it up. @scruffian @MaggieCabrera @mikachan @ajlende @getdave @draganescu @glendaviesnz @andrewserong @ramonjd @aaronrobertshaw

hover/focus/active states

Here's the Dev Note for this.

@oandregal looking at your list in your comment

This is the current list of stand-alone Dev Notes already drafted on the Make Blog:

• Fluid Font Sizes
• Styling Elements in Block Themes (@scruffian will expand a bit on the hover/focus/active states.)
• Spacing Presets

This is the list of theme.json PRs. See link list above. My idea would be to add "More Theme.json Updates" Dev Note covering the list and link to already existing Dev notes.

@jorgefilipecosta @t-hamano We already have a "Block Library Updates" (public preview) Dev note in the works, where we can add a paragraph about these PRs #42677 #43663

And if you can, also for #40554

What do you think? You can add it all in a comment on this issue together.

@bph combined dev note for the create-block stuff.

Create-Block Dev notes WP 6.1

#WordPress 6.1 introduces many updates and new features to the @wordpress/create-block.

New Features

Block Variants

The new –variant flag allows users of the tool to choose a block variant to be scaffolded. The internal templates provided by the create-block package support a dynamic and static variant with will scaffold a dynamic and static block respectively. If no variant is passed, the static variant is used.

Scaffolding using the dynamic variant:

npx @wordpress/create-block custom-block --variant=dynamic

Template authors can define variants by adding a variants object to the template definition with each property being the name of a variant and its value an object containing values that can add to or overwrite the default values defined in the defaultValues key. See the create-block-tutorial-template for an example of defining variants.

Related pull requests:

• #41289
• #43481

–no-plugin mode

A highly requested feature for the package was to be able to add additional blocks to an existing plugin. With the addition of the --no-plugin flag that is now possible!

When the command is run with the flag, a new set of block files will be created in the directory where the command was run in a directory named for the slug passed.

npx @wordpress/create-block custom-block --no-plugin

Related pull requests: #41642

Enhancements:

• I18n references have been removed from the internal templates to avoid potential issues with translated strings causing block validation errors ( #43035 )
• Improvements to the developer experience by prompting to continue the scaffolding process if the tool thinks system requirements are not met ( #42151, #42254 ) and some more general fixes to the scaffold to remove some warnings and errors ( #40479, #41273 ).
• Adds support for the new render block.json key ( #44185 )

Documentation

The documentation around creating External Templates has been split into its own section ( #43718) and links to the documentation in the associated create-block-tutorial-template have been fixed to link to the correct places ( #42839 ).

@bph Make draft if here: https://make.wordpress.org/core/?p=99350&preview=1&_ppp=79a1db742d