docs(core/config): add warning for deprecated options (#28216)

docs/usage/configuration-options.md

@@ -368,11 +368,6 @@ Solutions:
 
 ## branchName
 
-<!-- prettier-ignore -->
-!!! warning
-    We strongly recommended that you avoid configuring this field directly.
-    Use at your own risk.
-
 If you truly need to configure this then it probably means either:
 
 - You are hopefully mistaken, and there's a better approach you should use, so open a new "config help" discussion at the [Renovate discussions tab](https://github.com/renovatebot/renovate/discussions) or
@@ -473,11 +468,6 @@ If you want Renovate to sign off its commits, add the [`:gitSignOff` preset](./p
 
 ## commitMessage
 
-<!-- prettier-ignore -->
-!!! warning
-    We deprecated editing the `commitMessage` directly, and we recommend you stop using this config option.
-    Instead use config options like `commitMessageAction`, `commitMessageExtra`, and so on, to create the commit message you want.
-
 ## commitMessageAction
 
 This is used to alter `commitMessage` and `prTitle` without needing to copy/paste the whole string.

lib/config/options/index.ts

@@ -2065,6 +2065,8 @@ const options: RenovateOptions[] = [
     description: 'Branch name template.',
     type: 'string',
     default: '{{{branchPrefix}}}{{{additionalBranchPrefix}}}{{{branchTopic}}}',
+    deprecationMsg:
+      'We strongly recommended that you avoid configuring this field directly. Please edit `branchPrefix`, `additionalBranchPrefix`, or `branchTopic` instead.',
     cli: false,
   },
   {
@@ -2088,6 +2090,8 @@ const options: RenovateOptions[] = [
     type: 'string',
     default:
       '{{{commitMessagePrefix}}} {{{commitMessageAction}}} {{{commitMessageTopic}}} {{{commitMessageExtra}}} {{{commitMessageSuffix}}}',
+    deprecationMsg:
+      'We deprecated editing the `commitMessage` directly, and we recommend you stop using this config option. Instead use config options like `commitMessageAction`, `commitMessageExtra`, and so on, to create the commit message you want.',
     cli: false,
   },
   {
@@ -2158,9 +2162,11 @@ const options: RenovateOptions[] = [
   {
     name: 'prTitle',
     description:
-      'Pull Request title template (deprecated). Inherits from `commitMessage` if null.',
+      'Pull Request title template. Inherits from `commitMessage` if null.',
     type: 'string',
     default: null,
+    deprecationMsg:
+      'Direct editing of `prTitle` is now deprecated. Instead use config options like `commitMessageAction`, `commitMessageExtra`, and so on, as they will be passed through to `prTitle`.',
     cli: false,
   },
   {

lib/config/types.ts

@@ -434,6 +434,11 @@ export interface RenovateOptionBase {
   experimentalIssues?: number[];
 
   advancedUse?: boolean;
+
+  /**
+   * This is used to add depreciation message in the docs
+   */
+  deprecationMsg?: string;
 }
 
 export interface RenovateArrayOption<

tools/docs/config.ts

@@ -1,3 +1,4 @@
+import is from '@sindresorhus/is';
 import stringify from 'json-stringify-pretty-compact';
 import { getOptions } from '../../lib/config/options';
 import { allManagersList } from '../../lib/modules/manager';
@@ -92,6 +93,7 @@ function genTable(obj: [string, string][], type: string, def: any): string {
     'experimentalDescription',
     'experimentalIssues',
     'advancedUse',
+    'deprecationMsg',
   ];
   obj.forEach(([key, val]) => {
     const el = [key, val];
@@ -179,6 +181,17 @@ function genExperimentalMsg(el: Record<string, any>): string {
   return warning + '\n';
 }
 
+function genDeprecationMsg(el: Record<string, any>): string {
+  let warning =
+    '\n<!-- prettier-ignore -->\n!!! warning "This feature has been deprecated"\n';
+
+  if (el.deprecationMsg) {
+    warning += indent`${2}${el.deprecationMsg}`;
+  }
+
+  return warning + '\n';
+}
+
 function indexMarkdown(lines: string[]): Record<string, [number, number]> {
   const indexed: Record<string, [number, number]> = {};
 
@@ -241,6 +254,10 @@ export async function generateConfig(dist: string, bot = false): Promise<void> {
       if (el.experimental) {
         configOptionsRaw[footerIndex] += genExperimentalMsg(el);
       }
+
+      if (is.nonEmptyString(el.deprecationMsg)) {
+        configOptionsRaw[footerIndex] += genDeprecationMsg(el);
+      }
     });
 
   await updateFile(`${dist}/${configFile}`, configOptionsRaw.join('\n'));