paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 31 Packages Projects Releases Wiki Activity

beps/0009: switch libraries alternative to main proposal

Browse Source 
Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
This commit is contained in:
Patrik Oldsberg
2024-06-05 17:03:19 +02:00
parent 013b9b421b
commit e46744f7f5
1 changed files with 16 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
beps/0009-plugin-metadata/README.md
+16 -18
View File
@@ -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