From e46744f7f53ccf0b7e679328c114ce11594b3c6c Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 5 Jun 2024 17:03:19 +0200 Subject: [PATCH] beps/0009: switch libraries alternative to main proposal Signed-off-by: Patrik Oldsberg --- beps/0009-plugin-metadata/README.md | 34 ++++++++++++++--------------- 1 file changed, 16 insertions(+), 18 deletions(-) diff --git a/beps/0009-plugin-metadata/README.md b/beps/0009-plugin-metadata/README.md index a23a2d7ce4..b6ecd966d9 100644 --- a/beps/0009-plugin-metadata/README.md +++ b/beps/0009-plugin-metadata/README.md @@ -95,7 +95,7 @@ Packages that are part of the same plugin should always be managed within the sa Each plugin package must define a `backstage.pluginId` field, which is the same identifier as is used in the implementation of the plugin. This field is inferred from the package name by the `backstage-cli repo fix` command if it is not present. It should only be defined for plugin package, for example `@backstage/errors` should not define a plugin ID. The `backstage.pluginId` field is required when publishing a package with a plugin or module role, or a library role with "plugin" in its name. -The package relationships are defined in the `backstage.pluginPackages` field. The value of the field is an object where each key is the role of the package as defined by the `backstage.role` field, and the value is the package name. For example: +The package relationships are defined in the `backstage.pluginPackages` field. The value of the fields in an object with three optional keys, `frontend`, `backend`, and `libraries`. The `frontend` and `backend` fields must be the name of the frontend and backend plugin packages if present, while the `libraries` is an array of all library packages that are related to this plugin. For example: ```json { @@ -104,17 +104,19 @@ The package relationships are defined in the `backstage.pluginPackages` field. T "role": "frontend-plugin", "pluginId": "catalog", "pluginPackages": { - "frontend-plugin": "@backstage/plugin-catalog", - "backend-plugin": "@backstage/plugin-catalog-backend", - "web-library": "@backstage/plugin-catalog-react", - "node-library": "@backstage/plugin-catalog-node", - "common-library": "@backstage/plugin-catalog-common" + "frontend": "@backstage/plugin-catalog", + "backend": "@backstage/plugin-catalog-backend", + "libraries": [ + "@backstage/plugin-catalog-react", + "@backstage/plugin-catalog-node", + "@backstage/plugin-catalog-common" + ] } } } ``` -The `backstage.pluginPackages` field is generated and updated by the `backstage-cli repo fix` command based on the packages that are present in the workspace and their `backstage.pluginId` and `backstage.role` fields. There can only be a single package of each role with a given plugin ID. The `backstage.pluginPackages` field is required when publishing a package with a `backstage.pluginId` field that is not using a module role. +The `backstage.pluginPackages` field is generated and updated by the `backstage-cli repo fix` command based on the packages that are present in the workspace and their `backstage.pluginId` and `backstage.role` fields. The `backstage.pluginPackages` field is required when publishing a package with a `backstage.pluginId` field that is not using a module role. Module packages define their target plugin both via the `backstage.pluginId` field, as well as via `backstage.pluginPackage`. For example: @@ -161,9 +163,9 @@ None ## Alternatives -### Simplified Library Relationships +### Role-based Relationships -Rather than listing libraries for each role, we could simply have an array of libraries that are available for the plugin: +Rather than the proposed listing of related packages, we list packages by role instead. For example: ```json { @@ -174,21 +176,17 @@ Rather than listing libraries for each role, we could simply have an array of li "pluginPackages": { "frontend-plugin": "@backstage/plugin-catalog", "backend-plugin": "@backstage/plugin-catalog-backend", - "libraries": [ - "@backstage/plugin-catalog-react", - "@backstage/plugin-catalog-node", - "@backstage/plugin-catalog-common" - ] + "web-library": "@backstage/plugin-catalog-react", + "node-library": "@backstage/plugin-catalog-node", + "common-library": "@backstage/plugin-catalog-common" } } } ``` -A benefit of this approach is that it keeps the metadata simpler and reduces the need for conflict resolution logic since we can use the union of all listed library packages. +A benefit of this approach is that we know the role of each package upfront, although we'd likely want to validate the role of each package either way. -It also allows for the use-case of having multiple libraries of the same role, in case that would provide a benefit. Examples of this are the `@backstage/catalog-client` and `@backstage/catalog-model` packages. - -A downside of this approach could be that it may encourage a larger number of library packages, which is not necessarily what we want. Another downside is that the role of each package is not immediately available. +Another benefit is that there's a more strict requirement for only having a single package per role for each plugin, although this can also be considered a downside and limiting flexibility. ### Separate Metadata File