π§ Repository: Standard plugin metadata in package.json
nickboldt opened this issue Β· comments
π Description
Package.json dynamic plugin metadata
To make it easier to categorize dynamic plugins, this is a proposal to add some standardized keywords
, a new supported-versions
field to the backstage
field, and to encourage use of several standard package.json fields.
For example:
{
"name": "@janus-idp/backstage-plugin-myplugin",
"version": "0.7.2",
"license": "Apache-2.0",
"author": "Red Hat",
"maintainers": ["Plugin Dev Guy <pdg@mycorp.com>"],
"homepage": "https://mycorp.com/pdg-plugins",
"keywords": [
"support:production",
"lifecycle:active",
"groupid:myplugin",
"usage:ci-cd",
"usage:integration",
"feature:rbac-something-details",
"feature:audit-log",
"feature:scaled-deployments",
"restriction:single-instance"
],
"backstage": {
"role": "frontend-plugin",
"supported-versions": "^1.26.4"
}
}
Supported Backstage Versions
- Under the
backstage
field, add asupported-versions
set to a nodejs-standard version string. For example:
{
"backstage": {
"role": "frontend-plugin",
"supported-versions": "^1.26.4"
}
}
Keywords and field values
In order to achieve machine-readability, we need standardization. Here are the allowed values for the new keywords.
Support Level
This defines where the plugin is in its support lifecycle, in terms of quality and degree of support. Production (GA) is the highest support level, perhaps via paid subscription or other purchase model.
Below that is Technology Preview (TP), which seeks to eventually stabilize and move to production but is currently not fully supported.
Alpha and beta are for new, unsupported code.
- Add a keyword item, starting with
support:
and then one of 'alpha', 'beta', 'tech-preview', 'production'. For example:
{
"keywords": [
"support:production"
}
Lifecycle State
As plugins are created, evolve, and eventually discarded or abandoned, they will move though a lifecycle. These states might be able to be changed mechanically based on threshholds; for example if the last commit in the plugin's codebase was 6 months ago, it might be in maintenance mode; if known CVE issues are reported and not fixed, it might be moved to 'deprecated' or 'inactive' to warn consumers not to use it. Deprecated can also be used to identify that a new plugin replaces this old one.
- Add a keyword item, starting with
lifecycle:
and then one of: 'active', 'maintenance', 'deprecated', 'inactive', 'retired'. For example:
{
"keywords": [
"lifecycle:active"
}
Workspace or Functional Group
- Add a keyword item, starting with
groupid:
, then a freeform string to group multiple plugins under the same workspace/functional group, eg., github, ocm, myfeatureset. For example:
{
"keywords": [
"groupid:myplugin"
}
Usage, Feature, and Restriction Keywords
These three keyword prefixes can be used to define how a plugin is intended to be used, what it provides or interacts with, and any restrictions on its use. This information should also appear in the README or plugin documentation, but boiling that longform doc down to a set of keywords will allow better searching/filtering.
- Add a keyword item, starting with the three prefixes above, then a keyword chosen from a pool of available strings. For example:
{
"keywords": [
"usage:ci-cd",
"usage:search",
"usage:dashboard",
]
}
{
"keywords": [
"feature:rbac-aspect1",
"feature:rbac-aspect2",
"feature:audit-log",
"feature:scaled-deployments"
]
}
{
"keywords": [
"restriction:single-instance"
"restriction:ocp"
]
}
Other metadata fields
There are other standard fields that should be used, such as license
, author
, maintainers
, homepage
, and repository
. For example:
{
"license": "Apache-2.0",
"author": "Red Hat",
"maintainers": ["Plugin Dev Guy <pdg@mycorp.com>"],
"homepage": "https://mycorp.com/pdg-plugins",
"repository": {
"type": "git",
"url": "https://github.com/backstage/community-plugins",
"directory": "workspaces/mygroup/plugins/myplugin"
},
}
For Community-supported plugins not owned by a specific vendor, the Author
field could be set to Community
or Backstage Community
.
Community support can mean many things, such as the availability of learning resources, the frequency of updates, the quality of documentation, the size and diversity of the user base, and the responsiveness of the developers.
π Expected behavior
On commit / contribution, some tooling/linter/GHA action should make sure fields are filled out and CODEOWNERS is updated to match the new plugin's vendor/owner info
π Current Behavior
No standards exist for using keywords
and other fields like repository
. This means plugins will be more difficult to consume in a catalog/registry/marketplace.
π Reproduction steps
n/a
π Provide the context for the Bug.
n/a
π Have you spent some time to check if this bug has been raised before?
- I checked and didn't find similar issue
π’ Have you read the Code of Conduct?
- I have read the Code of Conduct
Are you willing to submit PR?
Yes I am willing to submit a PR!
Beyond the standards proposed above, it would be good to discuss how to implement validation of field data, or at minimum checking that plugins in the community-plugins repo are using a minimum list of required fields.
These should be at minimum these 9 items:
- license
- author (vendor(s) or "Backstage Community")
- maintainers (array of actual people, aligned to CODEOWNERS)
- homepage (could be this repo)
- repository (useful when published to npmjs)
- Support Level (keywords.support)
- Lifecycle State (keywords.lifecycle)
- backstage.role
- backstage.supported-versions
How to validate field content? could be via cli tooling when creating a plugin, or GH action when doing a release (eg., release fails if metadata missing/invalid)
Might also want some GH action to automatically change the Lifecycle State if a plugin workspace hasn't been touched in over 6mo or a year, switching to inactive
?
@backstage/maintainers for some more eyes here too on the proposed format.