From 0fcdc412e46ae86fb6acfb15ebd23dc32b5b3eda Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Thu, 13 Jun 2024 13:31:18 +0200
Subject: [PATCH] docs/package-metadata: document backstage fields

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
---
 docs/tooling/package-metadata.md | 76 ++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)

diff --git a/docs/tooling/package-metadata.md b/docs/tooling/package-metadata.md
index 31a77b7469..9497065a52 100644
--- a/docs/tooling/package-metadata.md
+++ b/docs/tooling/package-metadata.md
@@ -77,3 +77,79 @@ The package scripts as defined by [NPM](https://docs.npmjs.com/cli/v10/configuri
 ### `configSchema`
 
 The Backstage configuration schema for the package, as described by the [defining configuration](../conf/defining.md) section.
+
+### `backstage`
+
+This field is a collection of Backstage specific metadata fields. It is required for all Backstage packages, and any package that defines this field is considered to be part of the Backstage ecosystem. All sub-fields of this collection are defined below.
+
+### `backstage.role`
+
+This field defines the role of the package in the Backstage ecosystem. It can affect both the build process and runtime behavior, and signals the intended usage of the package to consumers. You can read more about this field in the [package roles](./cli/02-build-system.md#package-roles) section.
+
+### `backstage.pluginId`
+
+For any package that is part of a plugin, this field should be set to the plugin ID. This is the same ID as you would pass to the `createPlugin`, `createBackendPlugin`, or `createBackendModule` functions in the implementation of the package. It is also the same ID as the one described in the [name](#name) section.
+
+This field can be generated by the `backstage-cli repo fix --publish` command. It will be inferred from the based on the package [name](#name) and [role](#backstagerole). If the package name is not actually part of a plugin but still has `plugin-*` in its name, you can set this field to be explicitly `null`.
+
+The presence of this field is checked by the `backstage-cli package prepack` command, which is used to prepare a package for publishing.
+
+### `backstage.pluginPackages`
+
+For any package that is part of a plugin, this field should be set to a list of all packages that are directly part of the same plugin. This does not include module packages, only frontend and backend plugin packages as well as related libraries.
+
+This field can be generated by the `backstage-cli repo fix --publish` command. It checks for and lists all packages with the same [plugin ID](#backstagepluginid) in the workspace.
+
+The presence of this field is checked by the `backstage-cli package prepack` command, which is used to prepare a package for publishing.
+
+```js title="Example"
+{
+  "name": "@backstage/plugin-catalog",
+  "backstage": {
+    "role": "frontend-plugin",
+    "pluginId": "catalog",
+    "pluginPackages": [
+      "@backstage/plugin-catalog",
+      "@backstage/plugin-catalog-backend",
+      "@backstage/plugin-catalog-common",
+      "@backstage/plugin-catalog-node",
+      "@backstage/plugin-catalog-react"
+    ]
+  }
+  ...
+}
+```
+
+### `backstage.pluginPackage`
+
+For any module package of a plugin, this field should be set to the [name](#name) of the plugin package that this is a module for.
+
+This field can be generated by the `backstage-cli repo fix --publish` command. It checks for packages with a matching [plugin ID](#backstagepluginid) in the same workspace, but also knows the package names of the core feature plugin IDs such as `'catalog'`, `'auth'`, `'scaffolder'`, etc. If the package name can not be inferred, it has to be provided manually.
+
+The presence of this field is checked by the `backstage-cli package prepack` command, which is used to prepare a package for publishing.
+
+```js title="Example"
+{
+  "name": "@backstage/plugin-catalog-backend-module-github",
+  "backstage": {
+    "role": "backend-plugin-module",
+    "pluginId": "catalog",
+    "pluginPackage": "@backstage/plugin-catalog-backend"
+  }
+  ...
+}
+```
+
+### `backstage.moved`
+
+This field indicates that a package has been renamed and moved to a new location. This field is recognized by the Backstage CLI, where the version bump command will automatically switch to using the new package instead. The value of this field should be the new package name.
+
+```js title="Example"
+{
+  "name": "@backstage/plugin-azure-devops",
+  "backstage": {
+    "moved": "@backstage-community/plugin-azure-devops"
+  }
+  ...
+}
+```