Add 'since' option to deprecated function (#30017)

* Add 'since' option to deprecated function

See #23373.

* Fixes formatting issues

packages/deprecated/README.md

@@ -42,19 +42,21 @@ _Usage_
 import deprecated from '@wordpress/deprecated';
 
 deprecated( 'Eating meat', {
-	version: 'the future',
+	since: '2019.01.01'
+	version: '2020.01.01',
 	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.'
+// Logs: 'Eating meat is deprecated since version 2019.01.01 and will be removed from the earth in version 2020.01.01. Please use vegetables instead. Note: You may find it beneficial to transition gradually.'
 ```
 
 _Parameters_
 
 -   _feature_ `string`: Name of the deprecated feature.
 -   _options_ `[Object]`: Personalisation options
+-   _options.since_ `[string]`: Version in which the feature was deprecated.
 -   _options.version_ `[string]`: Version in which the feature will be removed.
 -   _options.alternative_ `[string]`: Feature to use instead
 -   _options.plugin_ `[string]`: Plugin name if it's a plugin feature

packages/deprecated/src/index.js

@@ -16,6 +16,7 @@ export const logged = Object.create( null );
  *
  * @param {string} feature               Name of the deprecated feature.
  * @param {Object} [options]             Personalisation options
+ * @param {string} [options.since]       Version in which the feature was deprecated.
  * @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
@@ -27,19 +28,21 @@ export const logged = Object.create( null );
  * import deprecated from '@wordpress/deprecated';
  *
  * deprecated( 'Eating meat', {
- * 	version: 'the future',
+ * 	since: '2019.01.01'
+ * 	version: '2020.01.01',
  * 	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.'
+ * // Logs: 'Eating meat is deprecated since version 2019.01.01 and will be removed from the earth in version 2020.01.01. Please use vegetables instead. Note: You may find it beneficial to transition gradually.'
  * ```
  */
 export default function deprecated( feature, options = {} ) {
-	const { version, alternative, plugin, link, hint } = options;
+	const { since, version, alternative, plugin, link, hint } = options;
 
 	const pluginMessage = plugin ? ` from ${ plugin }` : '';
+	const sinceMessage = since ? ` since version ${ since }` : '';
 	const versionMessage = version
 		? ` and will be removed${ pluginMessage } in version ${ version }`
 		: '';
@@ -48,7 +51,7 @@ export default function deprecated( feature, options = {} ) {
 		: '';
 	const linkMessage = link ? ` See: ${ link }` : '';
 	const hintMessage = hint ? ` Note: ${ hint }` : '';
-	const message = `${ feature } is deprecated${ versionMessage }.${ useInsteadMessage }${ linkMessage }${ hintMessage }`;
+	const message = `${ feature } is deprecated${ sinceMessage }${ versionMessage }.${ useInsteadMessage }${ linkMessage }${ hintMessage }`;
 
 	// Skip if already logged.
 	if ( message in logged ) {
@@ -60,6 +63,7 @@ export default function deprecated( feature, options = {} ) {
 	 *
 	 * @param {string}  feature             Name of the deprecated feature.
 	 * @param {?Object} options             Personalisation options
+	 * @param {string}  options.since       Version in which the feature was deprecated.
 	 * @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

packages/deprecated/src/test/index.js

@@ -21,6 +21,14 @@ describe( 'deprecated', () => {
 		expect( console ).toHaveWarnedWith( 'Eating meat is deprecated.' );
 	} );
 
+	it( 'should show a deprecation warning with a since', () => {
+		deprecated( 'Eating meat', { since: '2019.01.01' } );
+
+		expect( console ).toHaveWarnedWith(
+			'Eating meat is deprecated since version 2019.01.01.'
+		);
+	} );
+
 	it( 'should show a deprecation warning with a version', () => {
 		deprecated( 'Eating meat', { version: '2020.01.01' } );
 
@@ -31,12 +39,13 @@ describe( 'deprecated', () => {
 
 	it( 'should show a deprecation warning with an alternative', () => {
 		deprecated( 'Eating meat', {
+			since: '2019.01.01',
 			version: '2020.01.01',
 			alternative: 'vegetables',
 		} );
 
 		expect( console ).toHaveWarnedWith(
-			'Eating meat is deprecated and will be removed in version 2020.01.01. Please use vegetables instead.'
+			'Eating meat is deprecated since version 2019.01.01 and will be removed in version 2020.01.01. Please use vegetables instead.'
 		);
 	} );
 
@@ -67,14 +76,15 @@ describe( 'deprecated', () => {
 
 	it( 'should show a deprecation warning with a hint', () => {
 		deprecated( 'Eating meat', {
+			since: '2019.01.01',
 			version: '2020.01.01',
 			alternative: 'vegetables',
 			plugin: 'the earth',
 			hint: 'You may find it beneficial to transition gradually.',
 		} );
 
 		expect( console ).toHaveWarnedWith(
-			'Eating meat is deprecated and will be removed from the earth in version 2020.01.01. Please use vegetables instead. Note: You may find it beneficial to transition gradually.'
+			'Eating meat is deprecated since version 2019.01.01 and will be removed from the earth in version 2020.01.01. Please use vegetables instead. Note: You may find it beneficial to transition gradually.'
 		);
 	} );