Block API: Deprecate `property` source #7349

aduth · 2018-06-18T14:48:54Z

Related: #2751

This pull request seeks to deprecate the property source type. This was never publicly documented since it was always discouraged for use, but has been leveraged by core block implementations since earliest version of the plugin. Thus, while it's not expected that many plugin blocks will have used this source, there may be those where the core blocks had been used as a reference. The source will be removed in ~~3.2.0~~ 3.3.0.

There was a single instance of the property source being used incorrectly when a more appropriate alternative exists (code). textContent and innerHTML can be substituted with the text and html sources respectively.

The heading and list blocks were not as simple to transition, since they use nodeName as an indicator of heading level and ordered vs. unordered lists. These have been updated to new level (number) and ordered (boolean) attributes, serialized by the block comment attributes, including deprecated migrations for each block. Alternatively, we could consider an equivalent source type for retrieving the nodeName (or tag name) of a node, but this did not seem strictly necessary or a common enough use-case to justify.

Testing instructions:

Verify that existing posts containing lists and/or heading and/or code blocks are migrated gracefully.

Verify that a deprecated warning is shown for blocks which use the property source.

gziolo · 2018-06-18T15:02:03Z

I really like the proposed changes, in particular using nodeName was causing a lot of issues with having to parse it when applying any operations. It needs more detailed review but at the first glance, those changes look good.

gziolo

This looks great in general. I have some concerns regarding the deprecation strategy. While it is going to work for some time, what is your plan for getting rid of the source type completely. All deprecated schemas for blocks won’t work properly in such case.

gziolo · 2018-06-28T04:44:33Z

blocks/api/parser.js

@@ -70,6 +71,12 @@ export function matcherFromSource( sourceConfig ) {
 		case 'attribute':
 			return attr( sourceConfig.selector, sourceConfig.attribute );
 		case 'property':
+			deprecated( '`property` source', {
+				version: '3.3',


It’s now 3.4 🙁

gziolo · 2018-06-28T04:48:33Z

core-blocks/heading/index.js

+				...omit( schema, [ 'level' ] ),
+				nodeName: {
+					type: 'string',
+					source: 'property',


What is going to happen when we completely remove source type property?

gziolo · 2018-06-28T04:51:01Z

core-blocks/heading/index.js

@@ -108,11 +174,12 @@ export const settings = {
 	edit,

 	save( { attributes } ) {
-		const { align, nodeName, content } = attributes;
+		const { align, level, content } = attributes;
+		const tagName = 'h' + level;


It’s alwas gambling to mix string and number in JS, but this is okey. Just noting 😃

gziolo · 2018-06-28T04:53:53Z

core-blocks/list/index.js

+				...omit( schema, [ 'ordered' ] ),
+				nodeName: {
+					type: 'string',
+					source: 'property',


The same issue applies when deprecated source is removed.

gziolo · 2018-06-28T04:56:26Z

editor/components/document-outline/index.js

@@ -33,28 +33,6 @@ const multipleH1Headings = [
 	<em key="incorrect-message-multiple-h1">{ __( '(Multiple H1 headings are not recommended)' ) }</em>,
 ];

-const getHeadingLevel = ( heading ) => {


Yeah, the best part of the refactoring introduced 👌

aduth · 2018-06-28T12:54:01Z

I have some concerns regarding the deprecation strategy. While it is going to work for some time, what is your plan for getting rid of the source type completely.

I think ultimately it will have to be removed, even if that means the deprecation will stop working as well (meaning it may as well be removed). Also hints at a question of: Will deprecations be included in the final merge of Gutenberg? Or will we assume a clean slate at that point?

aduth · 2018-06-28T18:24:50Z

Rebased to resolve conflicts and bump the deprecation version. Also updated post-content.js demo content which I'd missed the first time around.

To the point on deprecation: I think we'll just have to bite the bullet, remove the source and all the existing deprecations with it.

mtias · 2018-06-29T12:08:49Z

core-blocks/heading/index.js

+	anchor: true,
+};
+
+const schema = {


We sometimes call this schema and sometimes attributes. We should be consistent.

We sometimes call this schema and sometimes attributes. We should be consistent.

It's a silly variable shadowing issue. We assign attributes in the edit function as a variable from props, which would conflict with a variable of the same name in the top-level scope.

More generally, I wish there were an easier way to inherit overlapping values between the deprecation and the current version. Nothing coming to mind at the moment, but I'll think on it some.

mtias · 2018-06-29T12:10:02Z

docs/reference/deprecated.md

@@ -13,6 +13,7 @@ Gutenberg's deprecation policy is intended to support backwards-compatibility fo
 - `blocks.BlockEdit` filter removed. Please use `editor.BlockEdit` instead.
 - `blocks.BlockListBlock` filter removed. Please use `editor.BlockListBlock` instead.
 - `blocks.MediaUpload` filter removed. Please use `editor.MediaUpload` instead.
+ - `property` source removed. Please use equivalent `text`, `html`, or `attribute` source, or comment attribute instead.


Hast to be moved to 3.2 list.

It's good as is, this list contains details when a given feature is going to be removed rather when it was deprecated.

gziolo · 2018-07-04T15:28:22Z

I fixed one bug which breaks deprecations for both blocks. With 1e0d25c it works as expected :)

gziolo

To the point on deprecation: I think we'll just have to bite the bullet, remove the source and all the existing deprecations with it.

Yes, I didn't come up with anything that would help mitigate this. Let's proceed and hope for the best. It's the last release where this kind of breaking change is acceptable. I'll merge as soon as I figure out why Travis error.s

youknowriad · 2018-07-15T11:15:37Z

core-blocks/heading/index.js

+		source: 'children',
+		selector: 'h1,h2,h3,h4,h5,h6',
+	},
+	level: {


Changing block attributes (nodeName replaced by level) is a breaking change and until now we don't warn about it (deprecated call). This broke one of my plugins, I wonder if we can/should ensure Backwards compatibility here.

Changing block attributes (nodeName replaced by level) is a breaking change and until now we don't warn about it (deprecated call).

I'm not sure I totally understand. The block attributes are a public API we should be guaranteeing compatibility for? Is this to do with block transforms? There is a deprecated definition, though I sense it would not be enough for transforms (at least as currently implemented, though maybe possible to support).

In this PR we removed the nodeName attribute from the heading block and added a level attribute. A plugin retrieving blocks (wp.data.select('code/editor').getBlocks()) can expect heading blocks to have a nodeName string attribute but it will fail since it will only find a level instead.

In this PR we removed the nodeName attribute from the heading block and added a level attribute. A plugin retrieving blocks (wp.data.select('code/editor').getBlocks()) can expect heading blocks to have a nodeName string attribute but it will fail since it will only find a level instead.

So hypothetically speaking: What's the point of deprecated if it's not enough to prevent cascading breaking effects?

What I'm saying is should we support both nodeName and level for some time coupled with deprecated? which hasn't been done in this PR (and it's not the only PR, just happened to be the one I noticed a bug with)

I understand the breakage and potential remedy, just trying to think through how this is communicated: When deprecating a block attribute, is it not enough for a developer to be confident in using deprecated, as this is all that we currently document in the handbook ? Does this apply to all blocks, or just core blocks ?

aduth added [Feature] Block API API that allows to express the block paradigm. [Feature] Blocks Overall functionality of blocks labels Jun 18, 2018

aduth force-pushed the remove/property-source branch from a9578cd to c3b8354 Compare June 25, 2018 14:50

aduth requested a review from a team June 25, 2018 14:50

aduth added this to the 3.2 milestone Jun 25, 2018

gziolo reviewed Jun 28, 2018

View reviewed changes

aduth force-pushed the remove/property-source branch from c3b8354 to 5e3b50e Compare June 28, 2018 18:23

mtias reviewed Jun 29, 2018

View reviewed changes

gziolo approved these changes Jul 4, 2018

View reviewed changes

aduth and others added 3 commits July 4, 2018 17:53

Blocks: Update blocks to avoid use of property source

5e38f33

Block API: Deprecate property source type

7ba1b98

Core blocks: Fix migrate functions for heading and list

75e0251

gziolo force-pushed the remove/property-source branch from 5a7ebec to ef36691 Compare July 4, 2018 15:57

Blocks: Try to make Eslint happy on Travis

7e9be8f

gziolo force-pushed the remove/property-source branch from ef36691 to 7e9be8f Compare July 4, 2018 15:58

gziolo merged commit 35f5a28 into master Jul 4, 2018

gziolo deleted the remove/property-source branch July 4, 2018 16:17

gziolo mentioned this pull request Jul 5, 2018

E2E tests: Add test case which will validate that blocks render properly when their definition changes #7719

Closed

youknowriad reviewed Jul 15, 2018

View reviewed changes

aduth mentioned this pull request Sep 21, 2018

Add inlineStyle matcher for sourcing block attributes #10074

Closed

4 tasks

gziolo mentioned this pull request Apr 30, 2019

Testing: Add integration tests for blocks with deprecations #15268

Merged

4 tasks

gziolo mentioned this pull request May 16, 2019

Block library: Extract deprecated field to their own files #15057

Merged

talldan mentioned this pull request Apr 30, 2020

Add block attribute selector for inline style #9439

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Block API: Deprecate `property` source #7349

Block API: Deprecate `property` source #7349

aduth commented Jun 18, 2018 •

edited

Loading

gziolo commented Jun 18, 2018

gziolo left a comment

gziolo Jun 28, 2018

gziolo Jun 28, 2018

gziolo Jun 28, 2018

gziolo Jun 28, 2018

gziolo Jun 28, 2018

aduth commented Jun 28, 2018

aduth commented Jun 28, 2018 •

edited

Loading

mtias Jun 29, 2018

aduth Jun 29, 2018 •

edited

Loading

mtias Jun 29, 2018

gziolo Jul 4, 2018

gziolo commented Jul 4, 2018

gziolo left a comment

youknowriad Jul 15, 2018

aduth Jul 16, 2018 •

edited

Loading

youknowriad Jul 16, 2018

aduth Jul 16, 2018

youknowriad Jul 16, 2018

aduth Jul 16, 2018

Block API: Deprecate property source #7349

Block API: Deprecate property source #7349

Conversation

aduth commented Jun 18, 2018 • edited Loading

gziolo commented Jun 18, 2018

gziolo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aduth commented Jun 28, 2018

aduth commented Jun 28, 2018 • edited Loading

Choose a reason for hiding this comment

aduth Jun 29, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gziolo commented Jul 4, 2018

gziolo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aduth Jul 16, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Block API: Deprecate `property` source #7349

Block API: Deprecate `property` source #7349

aduth commented Jun 18, 2018 •

edited

Loading

aduth commented Jun 28, 2018 •

edited

Loading

aduth Jun 29, 2018 •

edited

Loading

aduth Jul 16, 2018 •

edited

Loading