Adds developer docs for uiSettings

docs/developer/architecture/core/uisettings-service.asciidoc

@@ -3,14 +3,71 @@
 
 NOTE: The UI settings service is available both server and client side.
 
-=== Server side usage
+=== Overview
+
+UI settings are configurable from the Advanced Settings page in Management and control the behavior of {kib}. uiSettings are stored in a config saved object and, as such, conform to the same conditions as other <<saved-objects-service, Saved Objects>>.
+
+There are several ways to configure an advanced setting:
+
+- <<advanced-settings-ui, Through the Advanced Settings UI>>
+- <<uisettings-overrides, Locked via kibana.yml's uiSettings.overrides>>
+- <<client-side-usage, Through the client-side uiSettings Service>>
+- <<server-side-usage, Through the server-side uiSettings Service>>
+
+Keep in mind that once you add a new advanced setting, you cannot change or remove it without <<uisettings-migrations, registering a migration in core>>.
+
+[[advanced-settings-ui]]
+=== Configuration with Advanced Settings UI
+The uiSettings service is the programmatic interface to Kibana's Advanced Settings UI. Kibana plugins use the service to extend Kibana UI Settings Management with custom settings for their plugin.
+
+Configuration through the Advanced Settings UI is restricted to users authorised to acces the Advanced Settings page. Users who don't have permissions to change these values default to using the settings configured to the space they are in. Config saved objects can be shared between spaces.
+
+[[uisettings-overrides]]
+=== Configuration with UI settings overrides
+experimental[] When a setting is configured as an override in kibana.yml, it will override any other value stored in the config saved object. If an override is misconfigured, it will fail config validation and prevent Kibana from starting up. The override applies to Kibana as a whole for all spaces and users and the option will be disabled in the Advanced Settings page. We refer to these as "global" overrides.
+
+[[client-side-usage]]
+=== Client side usage
+On the client, the `uiSettings` service is exposed directly from `core` and the {kib-repo}blob/{branch}/docs/development/core/public/kibana-plugin-core-public.iuisettingsclient.md[client] provides plugins access to the `config` entries stored in {es}.
+
+In the interest of performance, `uiSettings` are cached. Any changes that require cache refreshes should register an instruction to reload the page when settings are configured in Advanced Settings using the `requiresPageReload` {kib-repo}blob/{branch}/docs/development/core/public/kibana-plugin-core-public.uisettingsparams.md[parameter].
+
+[source,typescript]
+----
+import { CoreSetup, Plugin } from 'src/core/public';
+
+export class MyPlugin implements Plugin<MyPluginSetup, MyPluginStart> {
+  public setup(core: CoreSetup): MyPluginSetup {
+    …
+    core.uiSettings.getUpdate$().subscribe(({ key, newValue }) => {
+      if (key === 'custom') {
+        // do something with changes...
+        myPluginService.register({
+          …
+        })
+      }
+    });
+    …
+  }
+
+  public start(core: CoreStart): MyPluginStart {
+    return {
+      …
+      settings: {
+        getCustomValue: () => core.uiSettings.get('custom'),
+        …
+      },
+    };
+  }
+}
 
-The program interface to <<advanced-options, UI settings>>.
-It makes it possible for Kibana plugins to extend Kibana UI Settings Management with custom settings.
+----
 
-See:
+[[server-side-usage]]
+=== Server side usage
+On the server, `uiSettings` are exposed directly from `core`.
 
-- {kib-repo}blob/{branch}/docs/development/core/server/kibana-plugin-core-server.uisettingsservicesetup.register.md[UI settings service Setup API docs]
+The following example shows how to {kib-repo}blob/{branch}/docs/development/core/server/kibana-plugin-core-server.uisettingsservicesetup.register.md[register] a new `custom` setting with a default value of '42'. When registering a new setting, you must provide a schema against which validations are performed on read and write. All the other {kib-repo}blob/{branch}/docs/development/core/server/kibana-plugin-core-server.uisettingsparams.md[parameters] are optional.
 
 [source,typescript]
 ----
@@ -38,3 +95,68 @@ export class MyPlugin implements Plugin {
 }
 
 ----
+
+[[uisettings-migrations]]
+=== Migrations
+
+[IMPORTANT]
+==============================================
+Migrations for 3rd party plugin advanced settings are not currently supported. If a 3rd party plugin registers an advanced setting, the setting is essentially permanent and cannot be fixed without manual intervention.
+==============================================
+
+To change or remove a `uiSetting`, the whole `config` Saved Object needs to be migrated. `uiSettings` {kib-repo}blob/{branch}/src/core/server/ui_settings/saved_objects/migrations.ts[migrations] are declared directly in the service.
+
+For example, if we wanted to remove a `custom` setting, or rename `my_setting:fourtyTwo` to `my_other_setting:fourtyTwo`, we'd need two migration entries, one for each change targeting the version in which these changes apply:
+
+[source,typescript]
+----
+export const migrations = {
+  ...
+  '8.1.0': (doc: SavedObjectUnsanitizedDoc<any>): SavedObjectSanitizedDoc<any> => ({
+  ...doc,
+  ...(doc.attributes && {
+    attributes: Object.keys(doc.attributes).reduce(
+      (acc, key) =>
+        [ 
+          // other settings to remove for 8.1.0...
+          'custom',
+        ].includes(key)
+          ? {
+              ...acc,
+            }
+          : {
+              ...acc,
+              [key]: doc.attributes[key],
+            },
+      {}
+    ),
+  }),
+  references: doc.references || [],
+  }),
+  '8.2.0': (doc: SavedObjectUnsanitizedDoc<any>): SavedObjectSanitizedDoc<any> => ({
+    ...doc,
+    ...(doc.attributes && {
+      attributes: Object.keys(doc.attributes).reduce(
+        (acc, key) =>
+          key.startsWith('my_setting:')
+            ? {
+                ...acc,
+                [key.replace('my_setting', 'my_other_setting')]: doc.attributes[key],
+              }
+            : {
+                ...acc,
+                [key]: doc.attributes[key],
+              },
+        {}
+      ),
+    }),
+    references: doc.references || [],
+  }),
+  …
+}
+----
+
+[TIP]
+==============================================
+Plugins can leverage the optional deprecation parameter on registration for handling deprecation notices and renames. The deprecation warnings are rendered in the Advanced Settings UI and should also be added to the <<settings,Configure Kibana>> guide.
+==============================================