docs: introduce deprecation docs + app-theme deprecation

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

docs/api/deprecations.md

@@ -0,0 +1,56 @@
+---
+id: deprecations
+title: Deprecations
+description: A list of active and past deprecations
+---
+
+## Introduction
+
+This page contains extended documentation for some of the deprecations in
+various parts of Backstage. It is not an exhaustive list as most deprecation
+only come in the form of a changelog notice and a console warning. The
+deprecations listed here are the ones that need a bit more guidance than what
+fits in a console message.
+
+### App Theme
+
+`Released 2021-11-12 in @backstage/core-plugin-api v0.1.13`
+
+In order to provide more flexibility in what types of themes can be used and how
+they are applied, the `theme` property on the `AppTheme` type is being
+deprecated and replaced by a `Provider` property instead. The `Provider`
+property is a React component that will be mounted at the root of the app
+whenever that theme is active. This also removes the tight connection to MUI and
+opens up for other type of themes, and removes the hardcoded usage of
+`<CssBaseline>`.
+
+To migrate an existing theme, remove the `theme` property and move it over to a
+new `Provider` component, using `ThemeProvider` from MUI to provide the new
+theme, along with `<CssBaseline>`. For example a theme that currently looks like
+this:
+
+```tsx
+const darkTheme = {
+  id: 'dark',
+  title: 'Dark Theme',
+  variant: 'dark',
+  icon: <DarkIcon />,
+  theme: darkTheme,
+};
+```
+
+Would be migrated to the following:
+
+```tsx
+const darkTheme = {
+  id: 'dark',
+  title: 'Dark Theme',
+  variant: 'dark',
+  icon: <DarkIcon />,
+  Provider: ({ children }) => (
+    <ThemeProvider theme={darkTheme}>
+      <CssBaseline>{children}</CssBaseline>
+    </ThemeProvider>
+  ),
+};
+```

microsite/sidebars.json

@@ -256,7 +256,8 @@
         "type": "subcategory",
         "label": "API Reference",
         "ids": ["reference/index"]
-      }
+      },
+      "api/deprecations"
     ],
     "Tutorials": [
       "tutorials/journey",

mkdocs.yml

@@ -164,6 +164,7 @@ nav:
   - API Reference:
       - Guides:
           - Utility APIs: 'api/utility-apis.md'
+      - Deprecations: 'api/deprecations.md'
   - Tutorials:
       - Future developer journey: 'tutorials/journey.md'
       - Migrating away from @backstage/core: 'tutorials/migrating-away-from-core.md'

packages/core-app-api/src/app/AppThemeProvider.tsx

@@ -98,7 +98,7 @@ export function AppThemeProvider({ children }: PropsWithChildren<{}>) {
   console.warn(
     "DEPRECATION WARNING: A provided app theme is using the deprecated 'theme' property " +
       'and should be migrated to use a Provider instead. ' +
-      'See https://backstage.io/docs/deprecations/TODO for more info.',
+      'See https://backstage.io/docs/api/deprecations#app-theme for more info.',
   );
 
   return (

packages/core-plugin-api/src/apis/definitions/AppThemeApi.ts

@@ -42,7 +42,7 @@ export type AppTheme = {
 
   /**
    * The specialized MaterialUI theme instance.
-   * @deprecated use Provider instead, see https://backstage.io/docs/deprecations/TODO
+   * @deprecated use Provider instead, see https://backstage.io/docs/api/deprecations#app-theme
    */
   theme: BackstageTheme;