Support adding a human-readable deprecation hint

utils/deprecation.js

@@ -7,13 +7,15 @@
  * @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
+ * @param {?string} options.hint        Additional message to help transition away from the deprecated feature.
  */
-export function deprecated( feature, { version, alternative, plugin, link } = {} ) {
+export 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.` : '';
 	const linkMessage = link ? ` See: ${ link }` : '';
-	const message = `${ feature } is deprecated and will be removed${ versionMessage }.${ useInsteadMessage }${ linkMessage }`;
+	const hintMessage = hint ? ` Note: ${ hint }` : '';
+	const message = `${ feature } is deprecated and will be removed${ versionMessage }.${ useInsteadMessage }${ linkMessage }${ hintMessage }`;
 
 	// eslint-disable-next-line no-console
 	console.warn( message );

utils/test/deprecation.js

@@ -52,4 +52,17 @@ describe( 'deprecated', () => {
 			'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'
 		);
 	} );
+
+	it( 'should show a deprecation warning with a hint', () => {
+		deprecated( 'Eating meat', {
+			version: 'the future',
+			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 the future. Please use vegetables instead. Note: You may find it beneficial to transition gradually.'
+		);
+	} );
 } );