Deprecated: Introduce new module with depreaction util

.eslintrc.js

@@ -46,25 +46,29 @@ module.exports = {
 				selector: 'ImportDeclaration[source.value=/^components$/]',
 				message: 'Use @wordpress/components as import path instead.',
 			},
+			{
+				selector: 'ImportDeclaration[source.value=/^data$/]',
+				message: 'Use @wordpress/data as import path instead.',
+			},
 			{
 				selector: 'ImportDeclaration[source.value=/^date$/]',
 				message: 'Use @wordpress/date as import path instead.',
 			},
 			{
-				selector: 'ImportDeclaration[source.value=/^editor$/]',
-				message: 'Use @wordpress/editor as import path instead.',
+				selector: 'ImportDeclaration[source.value=/^deprecated/]',
+				message: 'Use @wordpress/deprecated as import path instead.',
 			},
 			{
-				selector: 'ImportDeclaration[source.value=/^element$/]',
-				message: 'Use @wordpress/element as import path instead.',
+				selector: 'ImportDeclaration[source.value=/^dom$/]',
+				message: 'Use @wordpress/dom as import path instead.',
 			},
 			{
-				selector: 'ImportDeclaration[source.value=/^data$/]',
-				message: 'Use @wordpress/data as import path instead.',
+				selector: 'ImportDeclaration[source.value=/^editor$/]',
+				message: 'Use @wordpress/editor as import path instead.',
 			},
 			{
-				selector: 'ImportDeclaration[source.value=/^dom$/]',
-				message: 'Use @wordpress/dom as import path instead.',
+				selector: 'ImportDeclaration[source.value=/^element$/]',
+				message: 'Use @wordpress/element as import path instead.',
 			},
 			{
 				selector: 'ImportDeclaration[source.value=/^utils$/]',

blocks/api/registration.js

@@ -10,7 +10,7 @@ import { get, set, isFunction, some } from 'lodash';
  */
 import { applyFilters } from '@wordpress/hooks';
 import { select, dispatch } from '@wordpress/data';
-import { deprecated } from '@wordpress/utils';
+import deprecated from '@wordpress/deprecated';
 
 /**
  * Defined behavior of a block type.

core-blocks/index.js

@@ -6,7 +6,7 @@ import {
 	setDefaultBlockName,
 	setUnknownTypeHandlerName,
 } from '@wordpress/blocks';
-import { deprecated } from '@wordpress/utils';
+import deprecated from '@wordpress/deprecated';
 
 /**
  * Internal dependencies

data/persist.js

@@ -1,7 +1,7 @@
 /**
  * WordPress dependencies
  */
-import { deprecated } from '@wordpress/utils';
+import deprecated from '@wordpress/deprecated';
 
 /**
  * External dependencies

data/test/index.js

@@ -29,10 +29,6 @@ import {
 	toAsyncIterable,
 } from '../';
 
-jest.mock( '@wordpress/utils', () => ( {
-	deprecated: jest.fn(),
-} ) );
-
 // Mock data store to prevent self-initialization, as it needs to be reset
 // between tests of `registerResolvers` by replacement (new `registerStore`).
 jest.mock( '../store', () => () => {} );

docs/reference/deprecated.md

@@ -4,14 +4,15 @@ Gutenberg's deprecation policy is intended to support backwards-compatibility fo
 
  - `wp.data.withRehydratation` has been renamed to `wp.data.withRehydration`.
  - The `wp.editor.ImagePlaceholder` component is removed. Please use `wp.editor.MediaPlaceholder` instead.
+ - `wp.utils.deprecated` function removed. Please use `wp.deprecated` instead.
 
 ## 3.1.0
 
  - All components in `wp.blocks.*` are removed. Please use `wp.editor.*` instead.
  - `wp.blocks.withEditorSettings` is removed. Please use the data module to access the editor settings `wp.data.select( "core/editor" ).getEditorSettings()`.
  - All DOM utils in `wp.utils.*` are removed. Please use `wp.dom.*` instead.
  - `isPrivate: true` has been removed from the Block API. Please use `supports.inserter: false` instead.
- - `wp.utils.isExtraSmall` function removed. Please use `wp.viewport.*` instead.
+ - `wp.utils.isExtraSmall` function removed. Please use `wp.viewport.isExtraSmall` instead.
 
 ## 3.0.0
 

editor/components/image-placeholder/index.js

@@ -3,7 +3,7 @@
  */
 import { Component } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
-import { deprecated } from '@wordpress/utils';
+import deprecated from '@wordpress/deprecated';
 
 /**
  * Internal dependencies

editor/components/rich-text/index.js

@@ -24,10 +24,10 @@ import {
 	getRectangleFromRange,
 	getScrollContainer,
 } from '@wordpress/dom';
+import deprecated from '@wordpress/deprecated';
 import {
 	keycodes,
 	createBlobURL,
-	deprecated,
 } from '@wordpress/utils';
 import { withInstanceId, withSafeTimeout, Slot } from '@wordpress/components';
 import { withSelect } from '@wordpress/data';

editor/deprecated.js

@@ -7,7 +7,7 @@ import { forEach } from 'lodash';
  * WordPress dependencies
  */
 import { Component } from '@wordpress/element';
-import { deprecated } from '@wordpress/utils';
+import deprecated from '@wordpress/deprecated';
 import { withSelect } from '@wordpress/data';
 
 import {

lib/client-assets.php

@@ -115,10 +115,17 @@ function gutenberg_register_scripts_and_styles() {
 	);
 
 	// Editor Scripts.
+	wp_register_script(
+		'wp-deprecated',
+		gutenberg_url( 'build/deprecated/index.js' ),
+		array(),
+		filemtime( gutenberg_dir_path() . 'build/deprecated/index.js' ),
+		true
+	);
 	wp_register_script(
 		'wp-data',
 		gutenberg_url( 'build/data/index.js' ),
-		array( 'wp-element', 'wp-utils', 'wp-is-shallow-equal', 'lodash' ),
+		array( 'wp-deprecated', 'wp-element', 'wp-is-shallow-equal', 'lodash' ),
 		filemtime( gutenberg_dir_path() . 'build/data/index.js' ),
 		true
 	);
@@ -139,7 +146,7 @@ function gutenberg_register_scripts_and_styles() {
 	wp_register_script(
 		'wp-utils',
 		gutenberg_url( 'build/utils/index.js' ),
-		array( 'lodash', 'wp-dom' ),
+		array( 'lodash', 'wp-deprecated', 'wp-dom' ),
 		filemtime( gutenberg_dir_path() . 'build/utils/index.js' ),
 		true
 	);
@@ -206,7 +213,7 @@ function gutenberg_register_scripts_and_styles() {
 	wp_register_script(
 		'wp-blocks',
 		gutenberg_url( 'build/blocks/index.js' ),
-		array( 'wp-dom', 'wp-element', 'wp-utils', 'wp-hooks', 'wp-i18n', 'shortcode', 'wp-data', 'lodash' ),
+		array( 'wp-deprecated', 'wp-dom', 'wp-element', 'wp-utils', 'wp-hooks', 'wp-i18n', 'shortcode', 'wp-data', 'lodash' ),
 		filemtime( gutenberg_dir_path() . 'build/blocks/index.js' ),
 		true
 	);
@@ -234,6 +241,7 @@ function gutenberg_register_scripts_and_styles() {
 			'wp-blocks',
 			'wp-components',
 			'wp-core-data',
+			'wp-deprecated',
 			'wp-element',
 			'wp-editor',
 			'wp-i18n',
@@ -327,6 +335,7 @@ function gutenberg_register_scripts_and_styles() {
 			'wp-core-data',
 			'wp-data',
 			'wp-date',
+			'wp-deprecated',
 			'wp-dom',
 			'wp-i18n',
 			'wp-element',

packages/deprecated/.npmrc

@@ -0,0 +1 @@
+package-lock=false

packages/deprecated/README.md

@@ -0,0 +1,28 @@
+# @wordpress/deprecated
+
+Logs a message to notify developers about a deprecated feature.
+
+## Installation
+
+Install the module
+
+```bash
+npm install @wordpress/deprecated@next --save
+```
+
+## Usage
+
+```js
+import deprecated from '@wordpress/deprecated';
+
+deprecated( 'Eating meat', {
+	version: 'the future',
+	alternative: 'vegetables',
+	plugin: 'the earth',
+	hint: 'You may find it beneficial to transition gradually.',
+} );
+
+// Logs: 'Eating meat is deprecated and will be removed from the earth in the future. Please use vegetables instead. Note: You may find it beneficial to transition gradually.'
+```
+
+<br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>

packages/deprecated/package.json

@@ -0,0 +1,23 @@
+{
+	"name": "@wordpress/deprecated",
+	"version": "0.0.1",
+	"description": "Deprecation utility for WordPress",
+	"author": "WordPress",
+	"license": "GPL-2.0-or-later",
+	"keywords": [
+		"wordpress",
+		"deprecated"
+	],
+	"homepage": "https://github.com/WordPress/gutenberg/tree/master/packages/deprecated/README.md",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/WordPress/gutenberg.git"
+	},
+	"bugs": {
+		"url": "https://github.com/WordPress/gutenberg/issues"
+	},
+	"main": "src/index.js",
+	"publishConfig": {
+		"access": "public"
+	}
+}

utils/deprecation.js → packages/deprecated/src/index.js

@@ -9,7 +9,7 @@
  * @param {?string} options.link        Link to documentation
  * @param {?string} options.hint        Additional message to help transition away from the deprecated feature.
  */
-export function deprecated( feature, { version, alternative, plugin, link, hint } = {} ) {
+export default function deprecated( feature, { version, alternative, plugin, link, hint } = {} ) {
 	const pluginMessage = plugin ? ` from ${ plugin }` : '';
 	const versionMessage = version ? `${ pluginMessage } in ${ version }` : '';
 	const useInsteadMessage = alternative ? ` Please use ${ alternative } instead.` : '';

utils/test/deprecation.js → packages/deprecated/src/test/index.js

@@ -1,7 +1,7 @@
 /**
  * Internal dependencies
  */
-import { deprecated } from '../deprecation';
+import deprecated from '../';
 
 describe( 'deprecated', () => {
 	it( 'should show a deprecation warning', () => {

test/unit/jest.config.json

@@ -6,7 +6,7 @@
 	],
 	"moduleNameMapper": {
 		"@wordpress\\/(blocks|components|editor|data|utils|edit-post|viewport|plugins|core-data|core-blocks)$": "$1",
-		"@wordpress\\/(date|dom|element)$": "packages/$1/src"
+		"@wordpress\\/(date|dom|deprecated|element)$": "packages/$1/src"
 	},
 	"preset": "@wordpress/jest-preset-default",
 	"setupFiles": [

utils/deprecated.js

@@ -2,14 +2,10 @@
  * WordPress dependencies
  */
 import * as dom from '@wordpress/dom';
-
-/**
- * Internal dependencies
- */
-import { deprecated } from './deprecation';
+import originalDeprecated from '@wordpress/deprecated';
 
 const wrapFunction = ( functionName, source = dom ) => ( ...args ) => {
-	deprecated( 'wp.utils.' + functionName, {
+	originalDeprecated( 'wp.utils.' + functionName, {
 		version: '3.1',
 		alternative: 'wp.dom.' + functionName,
 		plugin: 'Gutenberg',
@@ -41,10 +37,20 @@ export const replace = wrapFunction( 'replace' );
 export const replaceTag = wrapFunction( 'replaceTag' );
 export const unwrap = wrapFunction( 'unwrap' );
 
+export function deprecated( ...params ) {
+	originalDeprecated( 'wp.utils.deprecated', {
+		version: '3.2',
+		alternative: 'wp.deprecated',
+		plugin: 'Gutenberg',
+	} );
+
+	return originalDeprecated( ...params );
+}
+
 export function isExtraSmall() {
-	deprecated( 'wp.utils.isExtraSmall', {
+	originalDeprecated( 'wp.utils.isExtraSmall', {
 		version: '3.1',
-		alternative: 'wp.viewport.*',
+		alternative: 'wp.viewport.isExtraSmall',
 		plugin: 'Gutenberg',
 	} );
 

utils/index.js

@@ -8,7 +8,6 @@ export { decodeEntities };
 export { keycodes };
 
 export * from './blob-cache';
-export * from './deprecation';
 export * from './mediaupload';
 export * from './terms';
 

webpack.config.js

@@ -137,6 +137,7 @@ const entryPointNames = [
 
 const gutenbergPackages = [
 	'date',
+	'deprecated',
 	'dom',
 	'element',
 ];
@@ -275,7 +276,7 @@ const config = {
 				return path;
 			},
 		} ),
-		new LibraryExportDefaultPlugin( [ 'dom-ready' ].map( camelCaseDash ) ),
+		new LibraryExportDefaultPlugin( [ 'deprecated', 'dom-ready' ].map( camelCaseDash ) ),
 	],
 	stats: {
 		children: false,