[Core deprecations] Add title field to deprecation info (#109840)

elastic · Sep 1, 2021 · 249c5fb · 249c5fb
1 parent f686164
commit 249c5fb
Show file tree

Hide file tree

Showing 34 changed files with 572 additions and 212 deletions.
diff --git a/.i18nrc.json b/.i18nrc.json
@@ -2,6 +2,7 @@
   "paths": {
     "alerts": "packages/kbn-alerts/src",
     "autocomplete": "packages/kbn-securitysolution-autocomplete/src",
+    "kbnConfig": "packages/kbn-config/src",
     "console": "src/plugins/console",
     "core": "src/core",
     "discover": "src/plugins/discover",

diff --git a/docs/development/core/server/kibana-plugin-core-server.deprecationsdetails.md b/docs/development/core/server/kibana-plugin-core-server.deprecationsdetails.md
@@ -18,6 +18,7 @@ export interface DeprecationsDetails
 |  [deprecationType](./kibana-plugin-core-server.deprecationsdetails.deprecationtype.md) | <code>'config' &#124; 'feature'</code> | (optional) Used to identify between different deprecation types. Example use case: in Upgrade Assistant, we may want to allow the user to sort by deprecation type or show each type in a separate tab.<!-- -->Feel free to add new types if necessary. Predefined types are necessary to reduce having similar definitions with different keywords across kibana deprecations. |
 |  [documentationUrl](./kibana-plugin-core-server.deprecationsdetails.documentationurl.md) | <code>string</code> |  |
 |  [level](./kibana-plugin-core-server.deprecationsdetails.level.md) | <code>'warning' &#124; 'critical' &#124; 'fetch_error'</code> | levels: - warning: will not break deployment upon upgrade - critical: needs to be addressed before upgrade. - fetch\_error: Deprecations service failed to grab the deprecation details for the domain. |
-|  [message](./kibana-plugin-core-server.deprecationsdetails.message.md) | <code>string</code> |  |
+|  [message](./kibana-plugin-core-server.deprecationsdetails.message.md) | <code>string</code> | The description message to be displayed for the deprecation. Check the README for writing deprecations in <code>src/core/server/deprecations/README.mdx</code> |
 |  [requireRestart](./kibana-plugin-core-server.deprecationsdetails.requirerestart.md) | <code>boolean</code> |  |
+|  [title](./kibana-plugin-core-server.deprecationsdetails.title.md) | <code>string</code> | The title of the deprecation. Check the README for writing deprecations in <code>src/core/server/deprecations/README.mdx</code> |
 
diff --git a/...evelopment/core/server/kibana-plugin-core-server.deprecationsdetails.message.md b/...evelopment/core/server/kibana-plugin-core-server.deprecationsdetails.message.md
@@ -4,6 +4,8 @@
 
 ## DeprecationsDetails.message property
 
+The description message to be displayed for the deprecation. Check the README for writing deprecations in `src/core/server/deprecations/README.mdx`
+
 <b>Signature:</b>
 
 ```typescript

diff --git a/.../development/core/server/kibana-plugin-core-server.deprecationsdetails.title.md b/.../development/core/server/kibana-plugin-core-server.deprecationsdetails.title.md
@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-core-server](./kibana-plugin-core-server.md) &gt; [DeprecationsDetails](./kibana-plugin-core-server.deprecationsdetails.md) &gt; [title](./kibana-plugin-core-server.deprecationsdetails.title.md)
+
+## DeprecationsDetails.title property
+
+The title of the deprecation. Check the README for writing deprecations in `src/core/server/deprecations/README.mdx`
+
+<b>Signature:</b>
+
+```typescript
+title: string;
+```
diff --git a/docs/development/core/server/kibana-plugin-core-server.deprecationsservicesetup.md b/docs/development/core/server/kibana-plugin-core-server.deprecationsservicesetup.md
@@ -21,6 +21,7 @@ export interface DeprecationsServiceSetup
 
 ```ts
 import { DeprecationsDetails, GetDeprecationsContext, CoreSetup } from 'src/core/server';
+import { i18n } from '@kbn/i18n';
 
 async function getDeprecations({ esClient, savedObjectsClient }: GetDeprecationsContext): Promise<DeprecationsDetails[]> {
   const deprecations: DeprecationsDetails[] = [];
@@ -29,52 +30,44 @@ async function getDeprecations({ esClient, savedObjectsClient }: GetDeprecations
   if (count > 0) {
     // Example of a manual correctiveAction
     deprecations.push({
-      message: `You have ${count} Timelion worksheets. The Timelion app will be removed in 8.0. To continue using your Timelion worksheets, migrate them to a dashboard.`,
+      title: i18n.translate('xpack.timelion.deprecations.worksheetsTitle', {
+        defaultMessage: 'Found Timelion worksheets.'
+      }),
+      message: i18n.translate('xpack.timelion.deprecations.worksheetsMessage', {
+        defaultMessage: 'You have {count} Timelion worksheets. The Timelion app will be removed in 8.0. To continue using your Timelion worksheets, migrate them to a dashboard.',
+        values: { count },
+      }),
       documentationUrl:
         'https://www.elastic.co/guide/en/kibana/current/create-panels-with-timelion.html',
       level: 'warning',
       correctiveActions: {
         manualSteps: [
-          'Navigate to the Kibana Dashboard and click "Create dashboard".',
-          'Select Timelion from the "New Visualization" window.',
-          'Open a new tab, open the Timelion app, select the chart you want to copy, then copy the chart expression.',
-          'Go to Timelion, paste the chart expression in the Timelion expression field, then click Update.',
-          'In the toolbar, click Save.',
-          'On the Save visualization window, enter the visualization Title, then click Save and return.',
+           i18n.translate('xpack.timelion.deprecations.worksheets.manualStepOneMessage', {
+             defaultMessage: 'Navigate to the Kibana Dashboard and click "Create dashboard".',
+           }),
+           i18n.translate('xpack.timelion.deprecations.worksheets.manualStepTwoMessage', {
+             defaultMessage: 'Select Timelion from the "New Visualization" window.',
+           }),
         ],
+        api: {
+          path: '/internal/security/users/test_dashboard_user',
+          method: 'POST',
+          body: {
+            username: 'test_dashboard_user',
+            roles: [
+              "machine_learning_user",
+              "enrich_user",
+              "kibana_admin"
+            ],
+            full_name: "Alison Goryachev",
+            email: "alisongoryachev@gmail.com",
+            metadata: {},
+            enabled: true
+          }
+        },
       },
     });
   }
-
-  // Example of an api correctiveAction
-  deprecations.push({
-    "message": "User 'test_dashboard_user' is using a deprecated role: 'kibana_user'",
-    "documentationUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-put-user.html",
-    "level": "critical",
-    "correctiveActions": {
-        "api": {
-            "path": "/internal/security/users/test_dashboard_user",
-            "method": "POST",
-            "body": {
-                "username": "test_dashboard_user",
-                "roles": [
-                    "machine_learning_user",
-                    "enrich_user",
-                    "kibana_admin"
-                ],
-                "full_name": "Alison Goryachev",
-                "email": "alisongoryachev@gmail.com",
-                "metadata": {},
-                "enabled": true
-            }
-        },
-        "manualSteps": [
-            "Using Kibana user management, change all users using the kibana_user role to the kibana_admin role.",
-            "Using Kibana role-mapping management, change all role-mappings which assing the kibana_user role to the kibana_admin role."
-        ]
-    },
-  });
-
   return deprecations;
 }
 

diff --git a/packages/kbn-config/BUILD.bazel b/packages/kbn-config/BUILD.bazel
@@ -35,6 +35,7 @@ RUNTIME_DEPS = [
   "//packages/kbn-logging",
   "//packages/kbn-std",
   "//packages/kbn-utility-types",
+  "//packages/kbn-i18n",
   "@npm//js-yaml",
   "@npm//load-json-file",
   "@npm//lodash",
@@ -48,6 +49,7 @@ TYPES_DEPS = [
   "//packages/kbn-logging",
   "//packages/kbn-std",
   "//packages/kbn-utility-types",
+  "//packages/kbn-i18n",
   "@npm//load-json-file",
   "@npm//rxjs",
   "@npm//@types/jest",

diff --git a/packages/kbn-config/src/deprecation/deprecation_factory.test.ts b/packages/kbn-config/src/deprecation/deprecation_factory.test.ts
@@ -48,7 +48,8 @@ describe('DeprecationFactory', () => {
                   "Replace \\"myplugin.deprecated\\" with \\"myplugin.renamed\\" in the Kibana config file, CLI flag, or environment variable (in Docker only).",
                 ],
               },
-              "message": "\\"myplugin.deprecated\\" is deprecated and has been replaced by \\"myplugin.renamed\\"",
+              "message": "Setting \\"myplugin.deprecated\\" has been replaced by \\"myplugin.renamed\\"",
+              "title": "Setting \\"myplugin.deprecated\\" is deprecated",
             },
           ],
         ]
@@ -103,7 +104,8 @@ describe('DeprecationFactory', () => {
                   "Replace \\"myplugin.oldsection.deprecated\\" with \\"myplugin.newsection.renamed\\" in the Kibana config file, CLI flag, or environment variable (in Docker only).",
                 ],
               },
-              "message": "\\"myplugin.oldsection.deprecated\\" is deprecated and has been replaced by \\"myplugin.newsection.renamed\\"",
+              "message": "Setting \\"myplugin.oldsection.deprecated\\" has been replaced by \\"myplugin.newsection.renamed\\"",
+              "title": "Setting \\"myplugin.oldsection.deprecated\\" is deprecated",
             },
           ],
         ]
@@ -130,7 +132,8 @@ describe('DeprecationFactory', () => {
                   "Remove \\"myplugin.deprecated\\" from the config.",
                 ],
               },
-              "message": "\\"myplugin.deprecated\\" is deprecated and has been replaced by \\"myplugin.renamed\\". However both key are present, ignoring \\"myplugin.deprecated\\"",
+              "message": "Setting \\"$myplugin.deprecated\\" has been replaced by \\"$myplugin.renamed\\". However, both keys are present. Ignoring \\"$myplugin.deprecated\\"",
+              "title": "Setting \\"myplugin.deprecated\\" is deprecated",
             },
           ],
         ]
@@ -172,7 +175,8 @@ describe('DeprecationFactory', () => {
                   "Replace \\"myplugin.deprecated\\" with \\"myplugin.renamed\\" in the Kibana config file, CLI flag, or environment variable (in Docker only).",
                 ],
               },
-              "message": "\\"myplugin.deprecated\\" is deprecated and has been replaced by \\"myplugin.renamed\\"",
+              "message": "Setting \\"myplugin.deprecated\\" has been replaced by \\"myplugin.renamed\\"",
+              "title": "Setting \\"myplugin.deprecated\\" is deprecated",
             },
           ],
         ]
@@ -212,7 +216,8 @@ describe('DeprecationFactory', () => {
                   "Replace \\"oldplugin.deprecated\\" with \\"newplugin.renamed\\" in the Kibana config file, CLI flag, or environment variable (in Docker only).",
                 ],
               },
-              "message": "\\"oldplugin.deprecated\\" is deprecated and has been replaced by \\"newplugin.renamed\\"",
+              "message": "Setting \\"oldplugin.deprecated\\" has been replaced by \\"newplugin.renamed\\"",
+              "title": "Setting \\"oldplugin.deprecated\\" is deprecated",
             },
           ],
         ]
@@ -264,7 +269,8 @@ describe('DeprecationFactory', () => {
                   "Remove \\"myplugin.deprecated\\" from the config.",
                 ],
               },
-              "message": "\\"myplugin.deprecated\\" is deprecated and has been replaced by \\"myplugin.renamed\\". However both key are present, ignoring \\"myplugin.deprecated\\"",
+              "message": "Setting \\"$myplugin.deprecated\\" has been replaced by \\"$myplugin.renamed\\". However, both keys are present. Ignoring \\"$myplugin.deprecated\\"",
+              "title": "Setting \\"myplugin.deprecated\\" is deprecated",
             },
           ],
         ]
@@ -293,10 +299,11 @@ describe('DeprecationFactory', () => {
             Object {
               "correctiveActions": Object {
                 "manualSteps": Array [
-                  "Remove \\"myplugin.deprecated\\" from the Kibana config file, CLI flag, or environment variable (in Docker only)",
+                  "Remove \\"myplugin.deprecated\\" from the Kibana config file, CLI flag, or environment variable (in Docker only).",
                 ],
               },
-              "message": "myplugin.deprecated is deprecated and is no longer used",
+              "message": "You no longer need to configure \\"myplugin.deprecated\\".",
+              "title": "Setting \\"myplugin.deprecated\\" is deprecated",
             },
           ],
         ]
@@ -325,10 +332,11 @@ describe('DeprecationFactory', () => {
             Object {
               "correctiveActions": Object {
                 "manualSteps": Array [
-                  "Remove \\"myplugin.section.deprecated\\" from the Kibana config file, CLI flag, or environment variable (in Docker only)",
+                  "Remove \\"myplugin.section.deprecated\\" from the Kibana config file, CLI flag, or environment variable (in Docker only).",
                 ],
               },
-              "message": "myplugin.section.deprecated is deprecated and is no longer used",
+              "message": "You no longer need to configure \\"myplugin.section.deprecated\\".",
+              "title": "Setting \\"myplugin.section.deprecated\\" is deprecated",
             },
           ],
         ]
@@ -375,10 +383,11 @@ describe('DeprecationFactory', () => {
             Object {
               "correctiveActions": Object {
                 "manualSteps": Array [
-                  "Remove \\"myplugin.deprecated\\" from the Kibana config file, CLI flag, or environment variable (in Docker only)",
+                  "Remove \\"myplugin.deprecated\\" from the Kibana config file, CLI flag, or environment variable (in Docker only).",
                 ],
               },
-              "message": "myplugin.deprecated is deprecated and is no longer used",
+              "message": "You no longer need to configure \\"myplugin.deprecated\\".",
+              "title": "Setting \\"myplugin.deprecated\\" is deprecated",
             },
           ],
         ]

diff --git a/packages/kbn-config/src/deprecation/deprecation_factory.ts b/packages/kbn-config/src/deprecation/deprecation_factory.ts
@@ -7,6 +7,8 @@
  */
 
 import { get } from 'lodash';
+import { i18n } from '@kbn/i18n';
+
 import {
   ConfigDeprecation,
   AddConfigDeprecation,
@@ -15,6 +17,13 @@ import {
   ConfigDeprecationCommand,
 } from './types';
 
+const getDeprecationTitle = (deprecationPath: string) => {
+  return i18n.translate('kbnConfig.deprecations.deprecatedSettingTitle', {
+    defaultMessage: 'Setting "{deprecationPath}" is deprecated',
+    values: { deprecationPath },
+  });
+};
+
 const _rename = (
   config: Record<string, any>,
   rootPath: string,
@@ -33,10 +42,18 @@ const _rename = (
   const newValue = get(config, fullNewPath);
   if (newValue === undefined) {
     addDeprecation({
-      message: `"${fullOldPath}" is deprecated and has been replaced by "${fullNewPath}"`,
+      title: getDeprecationTitle(fullOldPath),
+      message: i18n.translate('kbnConfig.deprecations.replacedSettingMessage', {
+        defaultMessage: `Setting "{fullOldPath}" has been replaced by "{fullNewPath}"`,
+        values: { fullOldPath, fullNewPath },
+      }),
       correctiveActions: {
         manualSteps: [
-          `Replace "${fullOldPath}" with "${fullNewPath}" in the Kibana config file, CLI flag, or environment variable (in Docker only).`,
+          i18n.translate('kbnConfig.deprecations.replacedSetting.manualStepOneMessage', {
+            defaultMessage:
+              'Replace "{fullOldPath}" with "{fullNewPath}" in the Kibana config file, CLI flag, or environment variable (in Docker only).',
+            values: { fullOldPath, fullNewPath },
+          }),
         ],
       },
       ...details,
@@ -47,11 +64,23 @@ const _rename = (
     };
   } else {
     addDeprecation({
-      message: `"${fullOldPath}" is deprecated and has been replaced by "${fullNewPath}". However both key are present, ignoring "${fullOldPath}"`,
+      title: getDeprecationTitle(fullOldPath),
+      message: i18n.translate('kbnConfig.deprecations.conflictSettingMessage', {
+        defaultMessage:
+          'Setting "${fullOldPath}" has been replaced by "${fullNewPath}". However, both keys are present. Ignoring "${fullOldPath}"',
+        values: { fullOldPath, fullNewPath },
+      }),
       correctiveActions: {
         manualSteps: [
-          `Make sure "${fullNewPath}" contains the correct value in the config file, CLI flag, or environment variable (in Docker only).`,
-          `Remove "${fullOldPath}" from the config.`,
+          i18n.translate('kbnConfig.deprecations.conflictSetting.manualStepOneMessage', {
+            defaultMessage:
+              'Make sure "{fullNewPath}" contains the correct value in the config file, CLI flag, or environment variable (in Docker only).',
+            values: { fullNewPath },
+          }),
+          i18n.translate('kbnConfig.deprecations.conflictSetting.manualStepTwoMessage', {
+            defaultMessage: 'Remove "{fullOldPath}" from the config.',
+            values: { fullOldPath },
+          }),
         ],
       },
       ...details,
@@ -75,10 +104,18 @@ const _unused = (
     return;
   }
   addDeprecation({
-    message: `${fullPath} is deprecated and is no longer used`,
+    title: getDeprecationTitle(fullPath),
+    message: i18n.translate('kbnConfig.deprecations.unusedSettingMessage', {
+      defaultMessage: 'You no longer need to configure "{fullPath}".',
+      values: { fullPath },
+    }),
     correctiveActions: {
       manualSteps: [
-        `Remove "${fullPath}" from the Kibana config file, CLI flag, or environment variable (in Docker only)`,
+        i18n.translate('kbnConfig.deprecations.unusedSetting.manualStepOneMessage', {
+          defaultMessage:
+            'Remove "{fullPath}" from the Kibana config file, CLI flag, or environment variable (in Docker only).',
+          values: { fullPath },
+        }),
       ],
     },
     ...details,

diff --git a/packages/kbn-config/src/deprecation/types.ts b/packages/kbn-config/src/deprecation/types.ts
@@ -19,6 +19,8 @@ export type AddConfigDeprecation = (details: DeprecatedConfigDetails) => void;
  * @public
  */
 export interface DeprecatedConfigDetails {
+  /* The title to be displayed for the deprecation. */
+  title?: string;
   /* The message to be displayed for the deprecation. */
   message: string;
   /* (optional) set false to prevent the config service from logging the deprecation message. */