Framework: Adding a deprecation helper (#5069)

blocks/block-description/index.js

@@ -2,6 +2,7 @@
  * WordPress dependencies
  */
 import { Component } from '@wordpress/element';
+import { deprecated } from '@wordpress/utils';
 /**
  * Internal dependencies
  */
@@ -10,8 +11,11 @@ import './style.scss';
 class BlockDescription extends Component {
 	constructor() {
 		super( ...arguments );
-		// eslint-disable-next-line no-console
-		console.warn( 'The wp.blocks.BlockDescription component is deprecated. Use the "description" block property instead.' );
+		deprecated( 'The wp.blocks.BlockDescription component', {
+			version: '2.4',
+			alternative: 'the "description" block property',
+			plugin: 'Gutenberg',
+		} );
 	}
 
 	render() {

blocks/block-description/test/index.js

@@ -16,7 +16,7 @@ describe( 'BlockDescription', () => {
 			expect( blockDescription.type() ).toBe( 'div' );
 			expect( blockDescription.text() ).toBe( 'Hello World' );
 			expect( console ).toHaveWarnedWith(
-				'The wp.blocks.BlockDescription component is deprecated. Use the "description" block property instead.'
+				'The wp.blocks.BlockDescription component is deprecated and will be removed from Gutenberg in 2.4. Please use the \"description\" block property instead.'
 			);
 		} );
 	} );

blocks/hooks/deprecated.js

@@ -8,6 +8,7 @@ import { includes } from 'lodash';
  */
 import { Component, RawHTML } from '@wordpress/element';
 import { addFilter } from '@wordpress/hooks';
+import { deprecated } from '@wordpress/utils';
 
 /**
  * Wrapper component for RawHTML, logging a warning about unsupported raw
@@ -19,13 +20,12 @@ export class RawHTMLWithWarning extends Component {
 
 		// Disable reason: We're intentionally logging a console warning
 		// advising the developer to upgrade usage.
-
-		// eslint-disable-next-line no-console
-		console.warn(
-			'Deprecated: Returning raw HTML from block `save` is not supported. ' +
-			'Use `wp.element.RawHTML` component instead.\n\n' +
-			'See: https://wordpress.org/gutenberg/handbook/block-api/block-edit-save/#save'
-		);
+		deprecated( 'Returning raw HTML from block `save`', {
+			version: '2.5',
+			alternative: '`wp.element.RawHTML` component',
+			plugin: 'Gutenberg',
+			link: 'https://wordpress.org/gutenberg/handbook/block-api/block-edit-save/#save',
+		} );
 	}
 
 	render() {

blocks/hooks/matchers.js

@@ -6,14 +6,16 @@ import { isFunction, mapValues } from 'lodash';
 /**
  * WordPress dependencies
  */
+import { deprecated } from '@wordpress/utils';
 import { addFilter } from '@wordpress/hooks';
 
 function warnAboutDeprecatedMatcher() {
-	// eslint-disable-next-line no-console
-	console.warn(
-		'Attributes matchers are deprecated and they will be removed in a future version of Gutenberg. ' +
-		'Please update your attributes definition https://wordpress.org/gutenberg/handbook/block-api/attributes/'
-	);
+	deprecated( 'Attributes matching using functions', {
+		version: '2.4',
+		alternative: 'the declarative attributes',
+		plugin: 'Gutenberg',
+		link: 'https://wordpress.org/gutenberg/handbook/block-api/attributes/',
+	} );
 }
 
 export const attr = ( selector, attribute ) => () => {

blocks/inspector-controls/index.js

@@ -18,6 +18,7 @@ import {
 	ToggleControl,
 } from '@wordpress/components';
 import { Component } from '@wordpress/element';
+import { deprecated } from '@wordpress/utils';
 
 export default function InspectorControls( { children } ) {
 	return (
@@ -30,8 +31,11 @@ export default function InspectorControls( { children } ) {
 const withDeprecation = ( componentName ) => ( OriginalComponent ) => {
 	class WrappedComponent extends Component {
 		componentDidMount() {
-			// eslint-disable-next-line no-console
-			console.warn( `wp.blocks.InspectorControls.${ componentName } is deprecated, use wp.components.${ componentName }.` );
+			deprecated( `wp.blocks.InspectorControls.${ componentName }`, {
+				version: '2.4',
+				alternative: `wp.components.${ componentName }`,
+				plugin: 'Gutenberg',
+			} );
 		}
 
 		render() {

blocks/media-upload/button.js

@@ -3,6 +3,7 @@
  */
 import { Component } from '@wordpress/element';
 import { Button, Tooltip } from '@wordpress/components';
+import { deprecated } from '@wordpress/utils';
 
 /**
  * Internal dependencies
@@ -11,8 +12,11 @@ import MediaUpload from './';
 
 class MediaUploadButton extends Component {
 	componentDidMount() {
-		// eslint-disable-next-line no-console
-		console.warn( 'MediaUploadButton is deprecated use wp.blocks.MediaUpload instead' );
+		deprecated( 'MediaUploadButton', {
+			version: '2.4',
+			alternative: 'wp.blocks.MediaUpload',
+			plugin: 'Gutenberg',
+		} );
 	}
 
 	render() {

blocks/rich-text/editable.js

@@ -1,3 +1,8 @@
+/**
+ * WordPress dependencies
+ */
+import { deprecated } from '@wordpress/utils';
+
 /**
  * Internal dependencies
  */
@@ -6,8 +11,11 @@ import RichText from './';
 class Editable extends RichText {
 	constructor() {
 		super( ...arguments );
-		// eslint-disable-next-line no-console
-		console.warn( 'Editable is deprecated, use wp.blocks.RichText instead.' );
+		deprecated( 'Editable', {
+			version: '2.5',
+			alternative: 'wp.blocks.RichText',
+			plugin: 'Gutenberg',
+		} );
 	}
 }
 

data/index.js

@@ -5,6 +5,11 @@ import { connect } from 'react-redux';
 import { createStore } from 'redux';
 import { flowRight, without, mapValues } from 'lodash';
 
+/**
+ * WordPress dependencies
+ */
+import { deprecated } from '@wordpress/utils';
+
 /**
  * Internal dependencies
  */
@@ -84,11 +89,10 @@ export function registerSelectors( reducerKey, newSelectors ) {
  */
 export function select( reducerKey ) {
 	if ( arguments.length > 1 ) {
-		// eslint-disable-next-line no-console
-		console.warn(
-			'Deprecated: `select` now accepts only a single argument: the reducer key. ' +
-			'The return value is an object of selector functions.'
-		);
+		deprecated( 'Calling select with multiple arguments', {
+			version: '2.4',
+			plugin: 'Gutenberg',
+		} );
 
 		const [ , selectorKey, ...args ] = arguments;
 		return select( reducerKey )[ selectorKey ]( ...args );

lib/client-assets.php

@@ -79,7 +79,7 @@ function gutenberg_register_scripts_and_styles() {
 	wp_register_script(
 		'wp-data',
 		gutenberg_url( 'data/build/index.js' ),
-		array( 'wp-element' ),
+		array( 'wp-element', 'wp-utils' ),
 		filemtime( gutenberg_dir_path() . 'data/build/index.js' )
 	);
 	wp_register_script(

utils/deprecation.js

@@ -0,0 +1,20 @@
+/**
+ * Logs a message to notify developpers about a deprecated feature.
+ *
+ * @param {string}  feature             Name of the deprecated feature.
+ * @param {?Object} options             Personalisation options
+ * @param {?string} options.version     Version in which the feature will be removed.
+ * @param {?string} options.alternative Feature to use instead
+ * @param {?string} options.plugin      Plugin name if it's a plugin feature
+ * @param {?string} options.link        Link to documentation
+ */
+export function deprecated( feature, { version, alternative, plugin, link } = {} ) {
+	const pluginMessage = plugin ? ` from ${ plugin }` : '';
+	const versionMessage = version ? `${ pluginMessage } in ${ version }` : '';
+	const useInsteadMessage = alternative ? ` Please use ${ alternative } instead.` : '';
+	const linkMessage = link ? ` See: ${ link }` : '';
+	const message = `${ feature } is deprecated and will be removed${ versionMessage }.${ useInsteadMessage }${ linkMessage }`;
+
+	// eslint-disable-next-line no-console
+	console.warn( message );
+}

utils/index.js

@@ -10,5 +10,6 @@ export { decodeEntities };
 export * from './blob-cache';
 export * from './mediaupload';
 export * from './terms';
+export * from './deprecation';
 
 export { viewPort };

utils/test/deprecation.js

@@ -0,0 +1,55 @@
+/**
+ * Internal dependencies
+ */
+import { deprecated } from '../deprecation';
+
+describe( 'deprecated', () => {
+	it( 'should show a deprecation warning', () => {
+		deprecated( 'Eating meat' );
+
+		expect( console ).toHaveWarnedWith(
+			'Eating meat is deprecated and will be removed.'
+		);
+	} );
+
+	it( 'should show a deprecation warning with a version', () => {
+		deprecated( 'Eating meat', { version: 'the future' } );
+
+		expect( console ).toHaveWarnedWith(
+			'Eating meat is deprecated and will be removed in the future.'
+		);
+	} );
+
+	it( 'should show a deprecation warning with an alternative', () => {
+		deprecated( 'Eating meat', { version: 'the future', alternative: 'vegetables' } );
+
+		expect( console ).toHaveWarnedWith(
+			'Eating meat is deprecated and will be removed in the future. Please use vegetables instead.'
+		);
+	} );
+
+	it( 'should show a deprecation warning with an alternative specific to a plugin', () => {
+		deprecated( 'Eating meat', {
+			version: 'the future',
+			alternative: 'vegetables',
+			plugin: 'the earth',
+		} );
+
+		expect( console ).toHaveWarnedWith(
+			'Eating meat is deprecated and will be removed from the earth in the future. Please use vegetables instead.'
+		);
+	} );
+
+	it( 'should show a deprecation warning with a link', () => {
+		deprecated( 'Eating meat', {
+			version: 'the future',
+			alternative: 'vegetables',
+			plugin: 'the earth',
+			link: 'https://en.wikipedia.org/wiki/Vegetarianism',
+		} );
+
+		expect( console ).toHaveWarnedWith(
+			'Eating meat is deprecated and will be removed from the earth in the future. Please use vegetables instead. See: https://en.wikipedia.org/wiki/Vegetarianism'
+		);
+	} );
+} );