Gutenberg and inevitable breaking changes

After spending a week on custom block development and diving into Gutenberg internals, I now understand why GB is shipping breaking changes every now and then.

I mean, it’s almost impossible to not break things because different components and APIs were created:

• by different people
• in a different way
• reviewed/merged by different reviewers as well,
• with different focus:
  • Block Editor preview area,
  • Block Editor settings panel
  • Site Editor
  • elsewhere (like on settings pages)
• etc.

Simple Examples

1. ToggleControl is a set of components wrapped inside BaseControl to provide label and help properties. One of the easiest to work with.
2. AnglePickerControl is a set of other components which are NOT wrapped inside BaseControl. And it doesn’t have a help property but it does have a label property. You have to wrap it into BaseControl, set the AnglePickerControl[label] to an empty string in order to be able to set label/help on the BaseControl level.
   Oh, and it also supports the className property which is not mentioned anywhere.
3. FontSizePicker is again, a set of other components and it does not have neither label nor help properties. So you cannot set them directly. Your own solution is to wrap it manually into the BaseControl and set label and help there.
   Oh, and you also must provide the unit inside your value (like '12px' instead of just 12 otherwise the units property won’t work – and this is not documented anywhere (not in storybook, not in readme, not in dev docs).
   Oh, and now you can’t easily add the BaseControl wrapper inside of the component because this will lead to doubling the wrapper for all those who added it manually (like I did).

I have a feeling that the Gutenberg project needs its own “Linus Torvalds” for at least half a year, ideally a year, to set up a set of very strict rules for quality, unification, review procedures, etc. Minus the yelling-in-writing part that Linus is famous for.

All the PRs must adhere to the Pull Request template that should be updated as well to also include something like this:

– [ ] I made sure that storybook, readme and all the docs are up-to-date with the changes in this PR.

I think several more sections and checkboxes should be added to it, to cover breaking changes, backward compatibility, technical choices, etc.

Those who can push directory to the repo, review and merge other people changes should adhere to the same rules.

That won’t help fixing the current codebase, but that will prepare the processes and adjust all the current PRs.

If certain components are created for certain areas of the Editor in mind or are designed to be used in certain areas only – they should be clearly marked as such, separated and “namespaced”.

IMO, it’s totally fine to have this kind of separation:

• @wordpress/components for generic components that are unified and can be used anywhere (all editors, custom settings pages);
• @wordpress/block-editor for the Block Editor specifically, with clear indication whether the block is expected to be used inside the InspectorControls component or in the preview area;
• @wordpress/site-editor for Site Editor specifically.

P.S. This whole post is my speculation from an outsider point of view. I may very much be wrong somewhere as I have no idea of Gutenberg project development internals.