Review formally stable APIs scheduled for hard deprecation.

[peterwilsoncc]

What problem does this address?

This is a sister issue to #40316 to discuss soft deprecated stable APIs.

The WordPress handbook lists backward compatibility as one of it's most important philosophies:

Major releases add new user features and developer APIs. Though typically a “major” version means you can break backwards compatibility (and indeed, it normally means that you have), WordPress strives to never break backwards compatibility. It’s one of our most important philosophies, and makes updates much easier on users and developers alike.

-- My emphasis, source

During the early, pre-merge, phase of Gutenberg development a decision was made to move away from that philosophy for the bleeding edge product.

This was a very sensible decision for the time as one of the purposes of a feature project is to trial various approaches and back them out before they make it to the stable product. Unfortunately the approach was not reviewed once Gutenberg became the block-editor, a feature of WordPress Core.

What is your proposed solution?

According to the version setting in calls to @wordpress/deprecated, the following formally stable APIs are scheduled for hard deprecation in the following versions. This will break backward compatibility.

Until a decision is made on the new backward compatibility policy is made by project leadership that applies to both the block editor and WordPress generally (ie, the code managed on trac) I think it would be best to remove the hard deprecation warning from core.

Such a discussion will need to be had in the wider dev chat in the #core slack channel to enable as much participation as possible.

Hard deprecated in 6.0

Sourced from the editor miscellaneous dev notes post for 6.0

• getReferenceByDistinctEdits selector.
• PreserveScrollInReorder component.
• dropZoneUIOnly prop in the MediaPlaceholder component.
• isDismissable prop in the Modal component.
• wp.data.plugins.control data module.

Each of these were soft deprecated in 5.4

Scheduled for hard deprecation in 6.1

Feature	Soft deprecated
CSS var --gallery-block--gutter-size	6.0

This is from the make post linked above

Scheduled for hard deprecation in 6.2

Feature	Soft deprecated
wp.blockEditor.RichText wrapperClassName prop	5.4
wp.blockEditor.RichText formattingControls prop	5.4
wp.components.IconButton	5.4
Button isDefault prop	5.4
UnitControl unit prop	5.6
wp.editor.RichText	5.3
wp.editor.Autocomplete	5.3
wp.editor.AlignmentToolbar	5.3
wp.editor.BlockAlignmentToolbar	5.3
wp.editor.BlockControls	5.3
wp.editor.BlockEdit	5.3
wp.editor.BlockEditorKeyboardShortcuts	5.3
wp.editor.BlockFormatControls	5.3
wp.editor.BlockIcon	5.3
wp.editor.BlockInspector	5.3
wp.editor.BlockList	5.3
wp.editor.BlockMover	5.3
wp.editor.BlockMover	5.3
wp.editor.BlockNavigationDropdown	5.3
wp.editor.BlockSelectionClearer	5.3
wp.editor.BlockSettingsMenu	5.3
wp.editor.BlockTitle	5.3
wp.editor.BlockToolbar	5.3
wp.editor.ColorPalette	5.3
wp.editor.ContrastChecker	5.3
wp.editor.CopyHandler	5.3
wp.editor.DefaultBlockAppender	5.3
wp.editor.FontSizePicker	5.3
wp.editor.Inserter	5.3
wp.editor.InnerBlocks	5.3
wp.editor.InspectorAdvancedControls	5.3
wp.editor.InspectorControls	5.3
wp.editor.PanelColorSettings	5.3
wp.editor.PlainText	5.3
wp.editor.RichTextShortcut	5.3
wp.editor.RichTextToolbarButton	5.3
wp.editor.MediaPlaceholder	5.3
wp.editor.MediaUpload	5.3
wp.editor.MediaUploadCheck	5.3
wp.editor.MultiSelectScrollIntoView	5.3
wp.editor.NavigableToolbar	5.3
wp.editor.ObserveTyping	5.3
wp.editor.SkipToSelectedBlock	5.3
wp.editor.URLInput	5.3
wp.editor.URLInputButton	5.3
wp.editor.URLPopover	5.3
wp.editor.Warning	5.3
wp.editor.WritingFlow	5.3
wp.editor.RichText.isEmpty()	5.3
wp.editor.createCustomColorsHOC()	5.3
wp.editor.getColorClassName()	5.3
wp.editor.getColorObjectByAttributeValues()	5.3
wp.editor.getColorObjectByColorValue()	5.3
wp.editor.getFontSize()	5.3
wp.editor.getFontSizeClass()	5.3
wp.editor.withColorContext()	5.3
wp.editor.withColors()	5.3
wp.editor.withFontSizes()	5.3
wp.data.dispatch( 'core/editor' ).resetBlocks	5.3
wp.data.dispatch( 'core/editor' ).receiveBlocks	5.3
wp.data.dispatch( 'core/editor' ).updateBlock	5.3
wp.data.dispatch( 'core/editor' ).updateBlockAttributes	5.3
wp.data.dispatch( 'core/editor' ).selectBlock	5.3
wp.data.dispatch( 'core/editor' ).startMultiSelect	5.3
wp.data.dispatch( 'core/editor' ).stopMultiSelect	5.3
wp.data.dispatch( 'core/editor' ).multiSelect	5.3
wp.data.dispatch( 'core/editor' ).clearSelectedBlock	5.3
wp.data.dispatch( 'core/editor' ).toggleSelection	5.3
wp.data.dispatch( 'core/editor' ).replaceBlocks	5.3
wp.data.dispatch( 'core/editor' ).moveBlocksDown	5.3
wp.data.dispatch( 'core/editor' ).moveBlocksUp	5.3
wp.data.dispatch( 'core/editor' ).moveBlockToPosition	5.3
wp.data.dispatch( 'core/editor' ).insertBlock	5.3
wp.data.dispatch( 'core/editor' ).insertBlocks	5.3
wp.data.dispatch( 'core/editor' ).showInsertionPoint	5.3
wp.data.dispatch( 'core/editor' ).hideInsertionPoint	5.3
wp.data.dispatch( 'core/editor' ).setTemplateValidity	5.3
wp.data.dispatch( 'core/editor' ).synchronizeTemplate	5.3
wp.data.dispatch( 'core/editor' ).mergeBlocks	5.3
wp.data.dispatch( 'core/editor' ).removeBlocks	5.3
wp.data.dispatch( 'core/editor' ).removeBlock	5.3
wp.data.dispatch( 'core/editor' ).toggleBlockMode	5.3
wp.data.dispatch( 'core/editor' ).startTyping	5.3
wp.data.dispatch( 'core/editor' ).stopTyping	5.3
wp.data.dispatch( 'core/editor' ).enterFormattedText	5.3
wp.data.dispatch( 'core/editor' ).exitFormattedText	5.3
wp.data.dispatch( 'core/editor' ).insertDefaultBlock	5.3
wp.data.dispatch( 'core/editor' ).updateBlockListSettings	5.3
wp.data.select( 'core/editor' ).getBlockName	5.3
wp.data.select( 'core/editor' ).isBlockValid	5.3
wp.data.select( 'core/editor' ).getBlockAttributes	5.3
wp.data.select( 'core/editor' ).getBlock	5.3
wp.data.select( 'core/editor' ).getBlocks	5.3
wp.data.select( 'core/editor' ).getClientIdsOfDescendants	5.3
wp.data.select( 'core/editor' ).getClientIdsWithDescendants	5.3
wp.data.select( 'core/editor' ).getGlobalBlockCount	5.3
wp.data.select( 'core/editor' ).getBlocksByClientId	5.3
wp.data.select( 'core/editor' ).getBlockCount	5.3
wp.data.select( 'core/editor' ).getBlockSelectionStart	5.3
wp.data.select( 'core/editor' ).getBlockSelectionEnd	5.3
wp.data.select( 'core/editor' ).getSelectedBlockCount	5.3
wp.data.select( 'core/editor' ).hasSelectedBlock	5.3
wp.data.select( 'core/editor' ).getSelectedBlockClientId	5.3
wp.data.select( 'core/editor' ).getSelectedBlock	5.3
wp.data.select( 'core/editor' ).getBlockRootClientId	5.3
wp.data.select( 'core/editor' ).getBlockHierarchyRootClientId	5.3
wp.data.select( 'core/editor' ).getAdjacentBlockClientId	5.3
wp.data.select( 'core/editor' ).getPreviousBlockClientId	5.3
wp.data.select( 'core/editor' ).getNextBlockClientId	5.3
wp.data.select( 'core/editor' ).getSelectedBlocksInitialCaretPosition	5.3
wp.data.select( 'core/editor' ).getMultiSelectedBlockClientIds	5.3
wp.data.select( 'core/editor' ).getMultiSelectedBlocks	5.3
wp.data.select( 'core/editor' ).getFirstMultiSelectedBlockClientId	5.3
wp.data.select( 'core/editor' ).getLastMultiSelectedBlockClientId	5.3
wp.data.select( 'core/editor' ).isFirstMultiSelectedBlock	5.3
wp.data.select( 'core/editor' ).isBlockMultiSelected	5.3
wp.data.select( 'core/editor' ).isAncestorMultiSelected	5.3
wp.data.select( 'core/editor' ).getMultiSelectedBlocksStartClientId	5.3
wp.data.select( 'core/editor' ).getMultiSelectedBlocksEndClientId	5.3
wp.data.select( 'core/editor' ).getBlockOrder	5.3
wp.data.select( 'core/editor' ).getBlockIndex	5.3
wp.data.select( 'core/editor' ).isBlockSelected	5.3
wp.data.select( 'core/editor' ).hasSelectedInnerBlock	5.3
wp.data.select( 'core/editor' ).isBlockWithinSelection	5.3
wp.data.select( 'core/editor' ).hasMultiSelection	5.3
wp.data.select( 'core/editor' ).isMultiSelecting	5.3
wp.data.select( 'core/editor' ).isSelectionEnabled	5.3
wp.data.select( 'core/editor' ).getBlockMode	5.3
wp.data.select( 'core/editor' ).isTyping	5.3
wp.data.select( 'core/editor' ).isCaretWithinFormattedText	5.3
wp.data.select( 'core/editor' ).getBlockInsertionPoint	5.3
wp.data.select( 'core/editor' ).isBlockInsertionPointVisible	5.3
wp.data.select( 'core/editor' ).isValidTemplate	5.3
wp.data.select( 'core/editor' ).getTemplate	5.3
wp.data.select( 'core/editor' ).getTemplateLock	5.3
wp.data.select( 'core/editor' ).canInsertBlockType	5.3
wp.data.select( 'core/editor' ).getInserterItems	5.3
wp.data.select( 'core/editor' ).hasInserterItems	5.3
wp.data.select( 'core/editor' ).getBlockListSettings	5.3
wp.nux	5.4
wp.components.ServerSideRender	5.3

Scheduled for removal in 6.3

Feature	Soft deprecated
wp.blockEditor.BlockColorsStyleSelector	6.1 (scheduled)
wp.data.dispatch( "core/block-editor" ).enterFormattedText	6.1 (scheduled)
wp.data.dispatch( "core/block-editor" ).exitFormattedText	6.1 (scheduled)
wp.data.select( "core/block-editor" ).isCaretWithinFormattedText	6.1 (scheduled)
range prop in Popover component	6.1 (scheduled)
wp.data.dispatch( 'core/editor' ).resetPost	6.0
wp.data.dispatch( 'core/editor' ).refreshPost	6.0
wp.data.dispatch( 'core/editor' ).createUndoLevel	6.0

Scheduled for removal in 6.4

Feature	Soft deprecated
Bottom margin styles for wp.blockEditor.LineHeightControl	6.0

Scheduled for removal in 6.5

Feature	Soft deprecated
Value attribute on the list block	6.0
Value attribute on the quote block	6.0
wp.dom.isNumberInput	6.1 (scheduled)

[adamziel]

You've done quite some work to gather all this data, thank you!

I'm torn here. I see your point, and yet removing these deprecation would de-facto change Gutenberg's policy without actually building a consensus and that could hurt the debate.

Until a decision is made on the new backward compatibility policy is made by project leadership that applies to both the block editor and WordPress generally (ie, the code managed on trac) I think it would be best to remove the hard deprecation warning from core.

Do you mean converging on a new policy in #40316? Because it seems like right now there's a tie right between WordPress's Backwards Compatibility commitment and the exploratory nature of Gutenberg. I can only see three ways out of that:

1. One side gives in (which some folks could take as "losing")
2. We find a solution that makes everyone happy, like what @gziolo explored in Plugin: Try API for making experiments limited to WordPress codebase #41278
3. Someone steps in as a tiebreaker

I'd love to make 2 happen. There's still a few months until WordPress 6.1 is released and these hard deprecations are in effect. In my perfect world we'd find a way to fulfill everyone's goals until then.

[adamziel]

Oh and just to add to that. I'm less worried about the existing deprecated APIs and more worried about the way of handling the new experimental APIs. A move like this one would take away a lot of confidence, as in "wait, I need an experimental thing but with this hard deprecations freeze I have no idea what to do".

[peterwilsoncc]

Do you mean converging on a new policy in #40316? Because it seems like right now there's a tie right between WordPress's Backwards Compatibility commitment and the exploratory nature of Gutenberg.

In part. I separated this discussion out because I think there is potential for different decisions for experimental APIs (REST and developer) and stable APIs. I was trying to keep #40316 focused on the experimental APIs but I think I failed, sorry.

Oh and just to add to that. I'm less worried about the existing deprecated APIs and more worried about the way of handling the new experimental APIs.

My order of concern differs:

1. Hard deprecation of stable/formally stable APIs (either immediate or after soft deprecation)
2. Long term experimental but unchanged (faux-stable)
3. Short term experimental in WP Core
4. Future/in plugin only (because of the work you, Greg and others are doing)

If the hard deprecations scheduled for 6.2 take place then I think it's fair to say WP no longer strives to maintain backward compatibility forever(tm). I don't necessarily think this is a bad thing.

It's difficult to do a comprehensive search due to script minimization but I think it will break a lot of code.

3. Someone steps in as a tiebreaker

This is potentially exactly what is needed from project leadership to get everyone on the same policy. 🤷 There is potential to meet in the middle. I think deciding on the stable APIs that are about to be pulled out is probably the easier decision.

[adamziel]

My order of concern differs:

Oh in terms of time-pressing priorities I agree. I should have clarified: I don't want to break the internet either. I was specifically referring to things I feel worried about. I'm somewhat at peace when thinking about the existing APIs because I have a hunch we'll end up keeping them in. I'm concerned about the new APIs and general policy because I don't see a clear way forward and it's a decision with major impact on the way Gutenberg is approached and developed.

This is potentially exactly what is needed from project leadership to get everyone on the same policy. 🤷 There is potential to meet in the middle. I think deciding on the stable APIs that are about to be pulled out is probably the easier decision.

💯

[peterwilsoncc]

Until a decision is made on the new backward compatibility policy is made by project leadership that applies to both the block editor and WordPress generally (ie, the code managed on trac) I think it would be best to remove the hard deprecation warning from core.

I've proposed a topic for the community summit to discuss the WP backward compatibility policy with the goal of coming up with a consistent approach across this and the wordpress-develop repos.

In other long threads, the performance impact of maintaining backward compatibility -- especially in JavaScript -- has been raised so I think that would be a helpful thing for contributors to discuss in person.

cc @adamziel @youknowriad @azaozz @noisysocks @mtias @josephahaden

[fabiankaegy]

@peterwilsoncc Do you happen to know if there has been any movement on a more formalized approach for this going forward?

There still is a growing list of __experimental & __unstable components and API's that were shipped in WordPress core and whilst we are shipping less now with the private API's functionality we don't have any answer for what happens with the API's already in core. #48743

[peterwilsoncc]

@fabiankaegy I don't think there has been any progress on how to handle these issues, I'm afraid.

There was discussion about aligning processes between the Gutenberg and WordPress Develop repos at the community summit but it needs a little follow up.

Removing the experimental public APIs is difficult enough, so I don't think it's possible to remove stable public APIs as developers have been advised to use them and, by implication, that they will have ongoing support.

[fabiankaegy]

Question then, Looking at the codebase currently there are ~74 instances where the deprecated function is used with the version parameter specified. (8x 6.2, 26x 6.3, 27x 6.4, etc.)

Without a strategy for actually removing these in core currently, this feels disingenuous. Should we remove the version prop from all of these for the time being?

We will retain the historical knowledge how long something has been marked as deprecated for through the since parameter but the version currently only causes confusion in my eyes.

If we think this makes sense I created a draft PR here: #56432

CC: @peterwilsoncc @youknowriad

[youknowriad]

I had wished that by this time, we'd come to an agreement on how to move forward with the backward compatibility strategy for JS APIs. It is clear to me (and others, you can ask any regular contributor) that not removing anything is not sustainable in a lot of ways. Bundle size is one reason, mental overhead is another. We can continue moving forward with the project without a clear path here.

If the summit was not sufficient to clarify this, how can we move forward responsibly? Continuously delaying this is not good enough.

[fabiankaegy]

@youknowriad I couldn't agree more that it isn't sustainable and at least for a good chunk of new APIs the private exports are at least a solid start to not introduce more of these non-stable components into the wild...

My point here primarily is that I don't think it currently makes sense to log console messages stating an exact core version for when something will be removed when those version numbers aren't correct because we have not come to a solution. Which is why I think removing the version till we have a formal solution for these old APIs may be a way to remove some of the confusion.

[peterwilsoncc]

If the summit was not sufficient to clarify this, how can we move forward responsibly? Continuously delaying this is not good enough.

I have two half thoughts (they are 100% not considered architectural proposals)

1. introduce some form of lazy loading of the deprecated functions after a transition period
   If an extender continues to use the functions then the file is loaded and execution is on hold while that happens. This removes the performance hit for up-to-date code while maintaining support. For devs using the dependency extractor we may be able to pre-empt this and include the files
2. For the editor package (which I think has the most deprecations) move the functions to another package and keep editor in place with the new package as a dependency.

As I say, half thoughts.