From d65587b71c6c9a9fb77aa2272ff16310e4d26ad6 Mon Sep 17 00:00:00 2001 From: Camila Belo Date: Wed, 21 Aug 2024 14:22:47 +0200 Subject: [PATCH 1/2] docs: add steps to drop support for legacy system on the plugins migration guide Co-authored-by: Johan Haals Signed-off-by: Camila Belo --- .../08-migrating.md | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/docs/backend-system/building-plugins-and-modules/08-migrating.md b/docs/backend-system/building-plugins-and-modules/08-migrating.md index 699852c494..33356e9ab8 100644 --- a/docs/backend-system/building-plugins-and-modules/08-migrating.md +++ b/docs/backend-system/building-plugins-and-modules/08-migrating.md @@ -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 { + 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/-backend/src/alpha.ts" +/** +* @alpha +// highlight-add-next-line +* @deprecated Please import from the root path instead. +*/ +export default createPlugin({ + //... +}); +``` From e4fdf1f02d5fcfb82a9c687b5ed97264693646d6 Mon Sep 17 00:00:00 2001 From: Camila Belo Date: Wed, 21 Aug 2024 16:38:29 +0200 Subject: [PATCH 2/2] refactor: apply review suggestions Signed-off-by: Camila Belo --- .../backend-system/building-plugins-and-modules/08-migrating.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/backend-system/building-plugins-and-modules/08-migrating.md b/docs/backend-system/building-plugins-and-modules/08-migrating.md index 33356e9ab8..8b2ea17de8 100644 --- a/docs/backend-system/building-plugins-and-modules/08-migrating.md +++ b/docs/backend-system/building-plugins-and-modules/08-migrating.md @@ -263,7 +263,7 @@ Given that you have followed the guide above to export your new backend plugin t ### 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. +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. If you are reusing the create router and relative imports in migrated plugins, ensure that you refactor the internal code to remove deprecated imports once the `createRouter` export gets deleted. It is recommended that you avoid the use of `@backstage/backend-common` and `@backstage/backend-tasks` in migrated plugins as they will be deleted together with the ending of support for the legacy system. There are instructions in most of the deprecated imports about how to stop using them once you have migrated to the new backend system. ```ts title="@backstage/plugin-kubernetes-backend/src/service/router.ts" import { KubernetesBuilder } from './KubernetesBuilder';