🔧 Repository: Standard plugin metadata in package.json

[nickboldt]

📜 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 a supported-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?

• [X] I checked and didn't find similar issue

🏢 Have you read the Code of Conduct?

• [X] I have read the Code of Conduct

Are you willing to submit PR?

Yes I am willing to submit a PR!

[nickboldt]

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 ?

[benjdlambert]

@backstage/maintainers for some more eyes here too on the proposed format.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.