docs: add steps to drop support for legacy system on the plugins migration guide

Co-authored-by: Johan Haals <johan.haals@gmail.com> Signed-off-by: Camila Belo <camilaibs@gmail.com>
2024-08-21 14:22:47 +02:00
parent 3bfbda0f28
commit d65587b71c
1 changed files with 64 additions and 0 deletions
@@ -255,3 +255,67 @@ backend.add(
 Checkout the [custom service implementations](https://backstage.io/docs/backend-system/building-backends/index#custom-service-implementations) documentation and also the [core service configurations](https://backstage.io/docs/backend-system/core-services/index) page in case you'd like to create your own custom mock factory for one or more services.

 3. Now you can finally start your plugin locally by running `yarn start` from the root folder of your plugin.
+
+## Remove support for the old backend system
+
+Given that you have followed the guide above to export your new backend plugin the steps to deprecate and remove the old backend plugin are the following:
+
+### Deprecate public exports other than the default export
+
+First of all make sure that `createRouter` and `routerOptions` are marked as deprecated to give users time and an indication to migrate to the new system (we recommend deprecating in one release and remove the deprecates in the following one).
+This is done by adding a `@deprecated` annotation to the legacy exports. It's worth noting that the plugin can continue using `createRouter` internally but it should not be exported as part of public api.
+
+```ts title="@backstage/plugin-kubernetes-backend/src/service/router.ts"
+import { KubernetesBuilder } from './KubernetesBuilder';
+
+/**
+* @public
+// highlight-add-next-line
+* @deprecated Please migrate to the new backend system.
+*/
+export interface RouterOptions {
+  logger: Logger;
+  config: Config;
+  catalogApi: CatalogApi;
+  clusterSupplier?: KubernetesClustersSupplier;
+  discovery: PluginEndpointDiscovery;
+}
+
+/**
+* @public
+// highlight-add-next-line
+* @deprecated Please migrate to the new backend system.
+*/
+export async function createRouter(
+  options: RouterOptions,
+): Promise<express.Router> {
+  const { router } = await KubernetesBuilder.createBuilder(options)
+    .setClusterSupplier(options.clusterSupplier)
+    .build();
+  return router;
+}
+```
+
+If your plugin contains an `api-report.md` file make sure to run `yarn build:api-reports` afterwards.
+It's recommended to inspect the api report and look for other exports other than the new backend plugin, they should most likely also be deprecated as plugins in the new backend system are extended using extension points and not directly by passing options. Any type of builder or helper methods that are used together with the backend plugin should be moved to a library package specifically for that plugin (e.g. a `plugin-kubernetes-backend-node` package, see the [package roles](https://backstage.io/docs/tooling/cli/build-system/#package-roles) documentation for more details).
+
+After removals of deprecations all your `index.ts` should contain is just the default export:
+
+```ts title="@backstage/plugin-kubernetes-backend/src/index.ts"
+export { kubernetesPlugin as default } from './plugin';
+```
+
+### Deprecate the `/alpha` subpath if it exists
+
+In cases where you previously supported the new backend system using an `alpha` export, please deprecate the alpha exports and re-export them from `index.ts`.
+
+```ts title="@backstage/<plugin-name>-backend/src/alpha.ts"
+/**
+* @alpha
+// highlight-add-next-line
+* @deprecated Please import from the root path instead.
+*/
+export default createPlugin({
+  //...
+});
+```