[Deprecation service] Using i18n for deprecation messages (#103422) (#…

…103889)

Co-authored-by: Ahmad Bamieh <ahmadbamieh@gmail.com>

src/core/server/deprecations/README.mdx

@@ -0,0 +1,210 @@
+---
+id: kibCoreDeprecationsService
+slug: /kibana-dev-docs/services/deprecations-service
+title: Core Deprecations service
+summary: The Deprecations service helps surface deprecated configs and features for plugins to our users
+date: 2021-06-27
+tags: ['kibana','dev', 'contributor', 'api docs']
+---
+
+# Core Deprecations service
+This guide is written in the format of a FAQ to help you get started using the deprecations service.
+For more details on the service contract we have documented all the service apis and properties under the
+deprecation service docs generated by in core.
+
+## What is the deprecations service?
+The deprecations service provides a way for the Kibana platform to communicate deprecated features
+and configs with its users. These deprecations are only communicated to the user if the deployment is using
+these features, allowing for a user tailored experience for upgrading the stack version.
+
+The Upgrade Assistant (UA) is the main consumer of these deprecations. The UA displays them to users and signals to
+Cloud that the Stack is ready for a major upgrade.
+
+
+## Where are deprecations displayed to users?
+The Upgrade Assistant (UA) in Kibana is consuming the core deprecations service in order to surface plugin
+deprecations. Each deprecation is required to provide manual steps that we display in the UI. Additionally
+each deprecation can provide an optional API to automatically resolve the deprecation.
+
+To check your plugin deprecations, go to the UA interface via **Stack Management > Stack > Upgrade Assistant**
+and click on `View deprecations` under the Kibana section.
+
+To display deprecations in the UA set `xpack.upgrade_assistant.readonly: false` in the kibana configurations.
+The UA is in read-only mode and will be enabled up until the last minor before the next major release.
+
+## How do I use this service for deprecated plugin configurations?
+The deprecations service automatically hooks deprecated configs with the deprecations service. 
+
+All the config deprecation functions (`unused`, `unusedFromRoot`, `rename`, `renameFromRoot`) accept an
+optional parameter to customize the deprecation details.
+
+To read more about the deprecation functions check `/kibana-dev-docs/corePluginApi` in the new doc
+system under `core.ConfigDeprecationFactory`. You can also check the `ConfigDeprecationFactory`
+[interface docs](../../../../../packages/kbn-config/src/deprecation/types.ts).
+
+### Example
+```ts
+export const config: PluginConfigDescriptor<ConfigType> = {
+  schema: configSchema,
+  deprecations: ({ renameFromRoot }) => [
+    renameFromRoot('ui_metric.debug', 'usageCollection.uiCounters.debug', {
+      documentationUrl: 'elastic.co/some-url',
+    }),
+  ],
+};
+```
+
+The service will show the following deprecation details when the users set the above deprecated kibana
+config `ui_metric.debug`.
+
+```ts
+{
+  deprecationsInfo:[{
+    level: 'critical',
+    message: `"ui_metric.debug" is deprecated and has been replaced by "usageCollection.uiCounters.debug"`,
+    documentationUrl: 'elastic.co/some-url',
+    correctiveActions:{
+      manualSteps: [
+        `Replace "ui_metric.debug" with "usageCollection.uiCounters.debug" in the Kibana config file, CLI flag, or environment variable (in Docker only).`,
+      ]
+    },
+    domainId: 'usageCollection',
+  }],
+}
+```
+
+#### Custom deprecations for plugin configs
+Custom config deprecation handling allows specifying the deprecation details via the `addDeprecation`.
+
+##### Example
+
+```ts
+export const config: PluginConfigDescriptor<ConfigSchema> = {
+  exposeToBrowser: {
+    defaultAppId: true,
+  },
+  schema: configSchema,
+  deprecations: () => [
+    (
+      completeConfig: Record<string, any>,
+      rootPath: string,
+      addDeprecation: AddConfigDeprecation
+    ) => {
+      if (
+        get(completeConfig, 'kibana.defaultAppId') === undefined &&
+        get(completeConfig, 'kibana_legacy.defaultAppId') === undefined
+      ) {
+        return completeConfig;
+      }
+      addDeprecation({
+        message: `kibana.defaultAppId is deprecated and will be removed in 8.0. Please use the "defaultRoute" advanced setting instead`,
+        correctiveActions: {
+          manualSteps: [
+            'Go to Stack Management > Advanced Settings',
+            'Update the "defaultRoute" setting under the General section',
+            'Remove "kibana.defaultAppId" from the kibana.yml config file',
+          ],
+        },
+      });
+      return completeConfig;
+    },
+  ],
+};
+```
+
+## How do I add deprecations for non-config plugin deprecations?
+Plugins are responsible for registering any deprecations during the `setup` lifecycle by using
+the deprecations service.
+
+Examples of non-config deprecations include things like
+- timelion sheets
+- kibana_user security roles 
+
+This service is not intended to be used for non-user facing deprecations or cases where the deprecation
+cannot be 'detected' by this mechanism.
+
+### Usage
+```ts
+coreSetup.deprecations.registerDeprecations({
+  getDeprecations: ({ esClient, savedObjectsClient }) => [{ ...`<list of deprecations>` }],
+});
+```
+
+The `getDeprecations` function is invoked when the user requests to see the deprecations affecting their deployment.
+The function provides a context object which contains a scoped Elasticsearch client and a saved objects client.
+
+To check the full TS types of the service please check the [generated core docs](../../../../docs/development/core/server/kibana-plugin-core-server.deprecationsservicesetup.md).
+
+### Example
+```ts
+import { DeprecationsDetails, GetDeprecationsContext } from 'src/core/server';
+
+async function getDeprecations({ esClient, savedObjectsClient }: GetDeprecationsContext): Promise<DeprecationsDetails[]> {
+  const deprecations: DeprecationsDetails[] = [];
+  const testDashboardUser = await getTestDashboardUser(savedObjectsClient);
+
+  if (testDashboardUser) {
+  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;
+}
+ ```
+
+## How do I implement the API corrective action?
+The deprecations API allows plugins to provide an API call that can be used to automatically fix specific deprecations.
+To do so create a `PUT` or `POST` route in your plugin and specify data you want to be passed in the payload for the deprecation.
+
+In the example above, `/internal/security/users/test_dashboard_user` will be called when users click on `Quick Resolve` in the UA. The service will automatically pass the body provided in the api corrective action to provide context to the route for fixing the deprecation.
+
+The deprecations service expects a `200` status code to recognize the corrective action as a success.
+
+## How do I test my deprecations?
+We recommend testing the route for your api corrective actions via unit and plugin functional tests.
+To check the deprecation in the UI please check the UA page.
+
+To test that your logic registering the deprecations with the deprecations service during `setup` is valid we recommend adding
+unit tests to check that the `getDeprecations` is returning the expected array of deprecations at different scenarios.
+
+Core provides mocks for the service which should help you focus on testing only your specific requirements.
+
+You can also use the deprecations service API; The deprecations service exposes an api `GET /api/deprecations/` which provides
+a list of deprecations and possible corrective actions required to resolve these entries. The context is scoped to the requesting
+user, hence a user with limited access might not be able to see all the deprecations affecting the deployment.
+
+Currently we do not have test objects to run functional tests against the Upgrade Assistant directly.
+
+## Should I use the service for all the deprecations before 8.0?
+Yes. Using this service should help users find and resolve any issues specific to their deployment before upgrading.
+We recommend adding a `documentationUrl` for every deprecation you expose to further assist our users if they need extra help.
+
+## Note on i18n
+We have decided to support i18n to the exposed deprecations for a better user experience when using the UA.
+We will inject `i18n` into the deprecation function to enable teams to use it before fully documenting its usage.
+For context follow [this issue](https://github.com/elastic/kibana/issues/99072).