Framework: Handle and upgrade deprecated blocks #3665

youknowriad · 2017-11-27T09:48:50Z

refs #2541 alternative to #3327

Instead of adding a "version" to the block comment and upgrading blocks version by version, this uses a simpler alternative where:

A block adds keeps a list of deprecated versions ( save, attributes and support )
When parsing a block if it's invalid, we try to find a "valid" deprecated version
If we find a corresponding version, we use its definition to parse the block attributes.

Testing instructions

Paste this in to the code editor (old quote HTML)

<!-- wp:quote {"style":1} -->
<blockquote class="wp-block-quote blocks-quote-style-1">
    <p>The editor will endeavour to create a new page and post building experience that makes writing rich posts effortless, and has “blocks” to make it easy what today might take shortcodes, custom HTML, or “mystery meat” embed discovery.</p><footer>Matt Mullenweg, 2017</footer></blockquote>
<!-- /wp:quote -->

Click outside the editable area
You'll notice the block is "migrated" to the last version with cite and you can still edit the block as expected in the visual editor

codecov · 2017-11-27T09:56:47Z

Codecov Report

Merging #3665 into master will decrease coverage by 0.27%.
The diff coverage is 77.77%.

@@            Coverage Diff             @@
##           master    #3665      +/-   ##
==========================================
- Coverage   37.74%   37.47%   -0.28%     
==========================================
  Files         279      277       -2     
  Lines        6743     6709      -34     
  Branches     1227     1219       -8     
==========================================
- Hits         2545     2514      -31     
  Misses       3536     3536              
+ Partials      662      659       -3

Impacted Files	Coverage Δ
blocks/api/parser.js	`98.41% <100%> (+0.41%)`	⬆️
blocks/library/quote/index.js	`18.6% <20%> (-3.28%)`	⬇️
editor/components/warning/index.js	`0% <0%> (-100%)`	⬇️
components/panel/color.js	`0% <0%> (-100%)`	⬇️
components/panel/row.js	`0% <0%> (-100%)`	⬇️
blocks/autocompleters/index.js	`0% <0%> (-42.11%)`	⬇️
editor/utils/mobile/index.js	`57.14% <0%> (-17.86%)`	⬇️
editor/components/post-publish-button/label.js	`83.33% <0%> (-4.17%)`	⬇️
blocks/editable/format-toolbar/index.js	`6.38% <0%> (-1.96%)`	⬇️
... and 27 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 0e60bd7...5a1ef20. Read the comment docs.

mtias · 2017-11-27T10:53:27Z

blocks/api/parser.js

@@ -181,6 +181,26 @@ export function createBlockWithFallback( name, innerHTML, attributes ) {
 		// as invalid, or future serialization attempt results in an error
 		block.originalContent = innerHTML;

+		// If the block is invalid, try to find an older compatible version


Maybe expand a bit on this comment, as it's important to understand why.

Quick one:

When a block is invalid, attempt to validate again using a supplied `deprecated` definition. This allows blocks to modify their attribute and markup structure without invalidating content written in previous formats.

mtias · 2017-11-27T10:54:21Z

blocks/library/quote/index.js

 registerBlockType( 'core/quote', {
 	title: __( 'Quote' ),
 	icon: 'format-quote',
 	category: 'common',

-	attributes: {


Why move this away?

Why move this away?

To address this, it's because the deprecated and original versions share most of the same attributes, with deprecated assigning into to reflect the original attributes behavior of citation.

I have concerns with block looking different at first sight when you open one to learn from, that i think we should minimize.

mtias · 2017-11-27T10:54:38Z

blocks/library/quote/index.js

 				) }
 			</blockquote>
 		);
 	},
+
+	deprecatedVersions: [


What about just deprecated here?

Sounds good to me

mtias · 2017-11-27T10:55:16Z

blocks/library/quote/index.js

+	deprecatedVersions: [
+		{
+			attributes: {
+				...blockAttributes,


I see. This is the kind of thing I think we should standardize. :)

mtias · 2017-11-27T10:57:25Z

blocks/library/quote/index.js

+				},
+			},
+
+			save( { attributes } ) {


I have a slight concern with accumulating save mechanisms just for validation, but I don't see an alternative. Might be worth moving all the deprecated definitions into a deprecated.js file to not burden the main js with additional save definitions.

What about the "attributes"? do you think we should share common attributes or maybe fine to duplicate?

mtias · 2017-11-27T10:57:42Z

I like this approach a lot more.

mtias · 2017-11-27T13:14:45Z

@youknowriad another side thing, I'd like to use this opportunity to change the class names used for the quote styles to be 'blocks-quote-style-1' = '' and 'blocks-quote-style-2' = 'is-large'.

youknowriad · 2017-11-27T13:17:09Z

@mtias Yep, sounds like a good idea. The quote here was just an example, thinking we should introduce these changes here or on follow-up PRs (with the several changes proposed by @samikeijonen )

mtias · 2017-11-27T13:19:23Z

I'd be ok with introducing here if it serves a good testing purpose.

mtias · 2017-11-27T13:37:49Z

blocks/library/quote/index.js

@@ -238,7 +240,7 @@ registerBlockType( 'core/quote', {

 		return (
 			<blockquote
-				className={ `blocks-quote-style-${ style }` }
+				className={ style === 2 ? 'is-large' : '' }


I think we could use default and large for the attribute itself? Or undefined and large maybe.

mmm, this means the value of the attribute can change between two versions, I'm going to introduce a migrate function to handle this

Mmm, can it be handled in the attribute itself as a fallback?

We might want to sit on it a bit otherwise.

No, we can't :(. Adding it is not so complex though 5dd81ce

Let's extract that commit into a separate PR so we can discuss the migration of values in isolation.

aduth · 2017-11-27T17:15:50Z

blocks/api/parser.js

+			let attributesParsedWithDeprecatedVersion;
+			const hasValidOlderVersion = find( blockType.deprecated, ( oldBlockType ) => {
+				const deprecatedBlockType = {
+					...omit( blockType, [ 'attributes', 'save', 'supports' ] ), // Parsing/Serialization properties


Do we need to omit here, or is it enough that the spread will override those properties?

Yes, we do because some of these properties are optional and we do not want to copy them in the old block's definition.

aduth · 2017-11-27T17:16:42Z

blocks/api/parser.js

@@ -181,6 +181,28 @@ export function createBlockWithFallback( name, innerHTML, attributes ) {
 		// as invalid, or future serialization attempt results in an error
 		block.originalContent = innerHTML;

+		// When a block is invalid, attempt to validate again using a supplied `deprecated` definition.


Should we extract this logic to a separate function, or would it be possible to take advantage of recursion here in returning via createBlockWithFallback using the deprecated block attempt attributes in place of the original?

Thanks for the suggestion Andrew, the code is better now. I preferred to avoid recursion because the logic is a bit simpler than createBlockWithFallback and it may include a specific "migrate" call in the future #3673

aduth · 2017-11-27T17:18:03Z

blocks/api/parser.js

+		// content written in previous formats.
+		if ( ! block.isValid && blockType.deprecated ) {
+			let attributesParsedWithDeprecatedVersion;
+			const hasValidOlderVersion = find( blockType.deprecated, ( oldBlockType ) => {


Array#some (or Lodash's equivalent) would be a more appropriate method here, since we don't care about the found value, just that it exists.

aduth · 2017-11-27T17:19:16Z

blocks/api/parser.js

+				};
+				const deprecatedBlockAttributes = getBlockAttributes( deprecatedBlockType, innerHTML, attributes );
+				const isValid = isValidBlock( innerHTML, deprecatedBlockType, deprecatedBlockAttributes );
+				attributesParsedWithDeprecatedVersion = isValid ? deprecatedBlockAttributes : undefined;


If we did extract this to a separate method, I could see this working well as an early return from a loop:

for ( let i = 0; i < deprecated.length; i++ ) { // ... if ( isValid ) { return deprecatedBlockAttributes; } }

aduth

Overall this looks good to me.

Two things I noted in testing:

The validation error for the original attempt shows even when there is a deprecated version available. This might be okay.
I added a {"style":2} block to post-content.js and it didn't upgrade to apply the is-large class name.

Try:

'<!-- wp:quote {"style":2} -->',
'<blockquote class="wp-block-quote blocks-quote-style-2"><p>The editor will endeavour to create a new page and post building experience that makes writing rich posts effortless, and has “blocks” to make it easy what today might take shortcodes, custom HTML, or “mystery meat” embed discovery.</p><footer>Matt Mullenweg, 2017</footer></blockquote>',
'<!-- /wp:quote -->',

aduth · 2017-12-04T14:51:03Z

blocks/api/test/parser.js

@@ -15,6 +16,15 @@ import {
 	setUnknownTypeHandlerName,
 } from '../registration';

+const expectFailingBlockValidation = () => {


Aside: I had a similar need for validation tests, wondering if we ought to put the effort into a generalized "expect console errors" assertion:

gutenberg/blocks/api/test/validation.js

Lines 33 to 43 in 9bfd837

/* eslint-disable no-console */

function expectError() {

expect( console.error ).toHaveBeenCalled();

console.error.mockClear();

}

function expectWarning() {

expect( console.warn ).toHaveBeenCalled();

console.warn.mockClear();

}

/* eslint-enable no-console */

Maybe expect( console ).toHaveLogged( 'error' ); set up in test/unit/setup-test-framework.js?

https://facebook.github.io/jest/docs/en/expect.html#expectextendmatchers

cc @gziolo

Nice idea! We are spying already on console warn and error methods: https://github.com/WordPress/gutenberg/blob/master/test/unit/setup-test-framework.js#L25. It should be easy to inplement 👍

aduth · 2017-12-04T14:56:11Z

blocks/api/test/parser.js

+						selector: 'div',
+					},
+				},
+				save: ( { attributes } ) => <div>{attributes.fruit}</div>,


Hmm, we have this rule, but it is not capturing this:

https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-curly-spacing.md

We should seek to include whitespace inside the curly for these cases for consistency with similar rules.

aduth · 2017-12-04T14:58:32Z

blocks/library/quote/index.js

 registerBlockType( 'core/quote', {
 	title: __( 'Quote' ),
 	icon: 'format-quote',
 	category: 'common',

-	attributes: {


Why move this away?

To address this, it's because the deprecated and original versions share most of the same attributes, with deprecated assigning into to reflect the original attributes behavior of citation.

…rge modifier

youknowriad · 2017-12-06T08:06:28Z

I added a {"style":2} block to post-content.js and it didn't upgrade to apply the is-large class name.

It did upgrade for me with this exact same code, what am I missing here?

mtias · 2017-12-07T12:59:51Z

The validation error for the original attempt shows even when there is a deprecated version available. This might be okay.

You mean the visual dialog prompting the user or in console?

youknowriad · 2017-12-07T15:45:43Z

I'm merging this one to include it in the release. It's working for me, can't reproduce the failing use-case

aduth · 2017-12-11T18:40:06Z

I can't reproduce my originally reported issue on master. Maybe a fluke 👍

youknowriad added the Framework Issues related to broader framework topics, especially as it relates to javascript label Nov 27, 2017

youknowriad self-assigned this Nov 27, 2017

youknowriad requested review from mtias, aduth and dmsnell November 27, 2017 09:48

youknowriad mentioned this pull request Nov 27, 2017

Blocks: Adding versioning and migrations to the Block API #3327

Closed

2 tasks

mtias reviewed Nov 27, 2017

View reviewed changes

youknowriad force-pushed the add/deprecated-blocks-handling branch from 39583ed to 37de716 Compare November 27, 2017 11:20

mtias reviewed Nov 27, 2017

View reviewed changes

aduth reviewed Nov 27, 2017

View reviewed changes

youknowriad force-pushed the add/deprecated-blocks-handling branch from 9240a66 to e6393ac Compare November 28, 2017 08:08

aduth reviewed Dec 4, 2017

View reviewed changes

youknowriad added 3 commits December 6, 2017 08:58

Framework: Handle and upgrade deprecated blocks

06fe513

Framework: Rename "deprecatedVersions" to "deprecated"

3863e50

Quote Block: Drop the blocks-quote-style-* styles in favor of a is-la…

3f94460

…rge modifier

youknowriad force-pushed the add/deprecated-blocks-handling branch from e6393ac to 5a1ef20 Compare December 6, 2017 08:06

Parser: Extract the deprecated versions handler to a separate function

bd6f99c

youknowriad force-pushed the add/deprecated-blocks-handling branch from 5a1ef20 to bd6f99c Compare December 7, 2017 15:36

youknowriad merged commit 18a7b10 into master Dec 7, 2017

mtias mentioned this pull request Dec 7, 2017

Quote and pullquote blocks: consider to use a cite element for the citation instead of a footer #2647

Closed

aduth mentioned this pull request Dec 12, 2017

Update cover image markup and CSS #3444

Merged

3 tasks

danielbachhuber mentioned this pull request Mar 28, 2018

In blockquotes, use cite element instead of footer. #2647 #2859

Closed

3 tasks

gziolo deleted the add/deprecated-blocks-handling branch May 7, 2018 11:15

	/* eslint-disable no-console */
	function expectError() {
	expect( console.error ).toHaveBeenCalled();
	console.error.mockClear();
	}

	function expectWarning() {
	expect( console.warn ).toHaveBeenCalled();
	console.warn.mockClear();
	}
	/* eslint-enable no-console */

Framework: Handle and upgrade deprecated blocks #3665

Framework: Handle and upgrade deprecated blocks #3665

Conversation

youknowriad commented Nov 27, 2017

codecov bot commented Nov 27, 2017 • edited Loading

Codecov Report

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

youknowriad Nov 27, 2017 • edited Loading

Choose a reason for hiding this comment

mtias commented Nov 27, 2017

mtias commented Nov 27, 2017

youknowriad commented Nov 27, 2017

mtias commented Nov 27, 2017

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

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 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

youknowriad commented Dec 6, 2017

mtias commented Dec 7, 2017

youknowriad commented Dec 7, 2017

aduth commented Dec 11, 2017

codecov bot commented Nov 27, 2017 •

edited

Loading

youknowriad Nov 27, 2017 •

edited

Loading