diff --git a/packages/deprecated/README.md b/packages/deprecated/README.md index 491752b291f104..7528df707e4c78 100644 --- a/packages/deprecated/README.md +++ b/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 diff --git a/packages/deprecated/src/index.js b/packages/deprecated/src/index.js index 13f11a24a0df77..d9b367c11ce557 100644 --- a/packages/deprecated/src/index.js +++ b/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 diff --git a/packages/deprecated/src/test/index.js b/packages/deprecated/src/test/index.js index 94a4823dcd4a94..62f02079f0d195 100644 --- a/packages/deprecated/src/test/index.js +++ b/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,6 +76,7 @@ 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', @@ -74,7 +84,7 @@ describe( 'deprecated', () => { } ); 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.' ); } );