beps/0008: fill out the rest of the proposal

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

beps/0008-plugin-metadata/README.md

@@ -77,15 +77,61 @@ The purpose of this section is to define how we make it as simple as possible to
 
 Validation and automation is split into two separate phases. The first is phase is manual tooling that is run by the developer and typically validated in CI, for example the `backstage-cli fix` command. The second phase is validation at the time of publishing the package, which is done by the `yarn prepack` command. By splitting the tooling into these two phases we can ensure that a minimal set of metadata is present for all packages published using the Backstage tooling, but at the same time avoid adding unnecessary friction to the development process.
 
-An important aspect to take into consideration is that most Backstage packages are never published to NPM, as they're part of an internal monorepo and get built directly into an internal Backstage application. Defining the full set of metadata for these packages is likely to be wasteful, which means we
+An important aspect to take into consideration is that most Backstage packages are never published to NPM, as they're part of an internal monorepo and get built directly into an internal Backstage application. Defining the full set of metadata for these packages is likely to be wasteful, which means we should avoid building too many requirements for that path.
+
+### Package Metadata and Documentation
+
+This section defines our strategy for defining new metadata fields, and how they are documented.
+
+To the furthest extent possible we will rely on established standards for `package.json` fields, but we will do so within the bounds of the intended usage of these fields. This means that we will only use existing fields for their intended purpose, and instead define new fields if no existing field is suitable. An index of existing fields is found in the [NPM documentation](https://docs.npmjs.com/cli/v10/configuring-npm/package-json), but we are not limited to this list. Any fields that we can find within the NPM ecosystem may be used, as long as they are well established, for example if there could be a use for the `prettier` field [defined by prettier](https://prettier.io/docs/en/configuration.html#sharing-configurations).
+
+In the case of new fields we always define them to be part of the top-level `"backstage"` field. The assumption is that any field that we define will always be tied to the Backstage ecosystem, even in the case of general fields such as "lifecycle". The only exception to this is if we believe that a field is generic enough that it could genuinely become part of the broader NPM ecosystem.
+
+All fields must be documented in a new section of the "Tooling" documentation on backstage.io. This documentation should include a description of the field, what it is used for, and what the expected values are. The documentation must also mention whether the field is expected to be filled in manually, or if it will be generated by tooling. Changes to this documentation must be approved by the Backstage core maintainers, it is not owned by individual project area maintainers.
 
 ### Package Relationships
 
-### Package Metadata Documentation
+This section defines how we associate packages from the same plugin with each other.
+
+Package the are part of the same plugin should always be managed within the same monorepo and workspace. This does not apply to modules for a plugin, which may be hosted separately, but may still need to refer to the plugin that it is a module for.
+
+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:
+
+```json
+{
+  "backstage": {
+    "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"
+    }
+  }
+}
+```
+
+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.
+
+Module packages define their target plugin both via the `backstage.pluginId` field, as well as via `backstage.pluginPackage`. For example:
+
+```json
+{
+  "backstage": {
+    "pluginId": "catalog",
+    "pluginPackage": "@backstage/plugin-catalog-backend"
+  }
+}
+```
+
+The `backstage.pluginPackage` field is required when publishing a package with a module role.
 
 ## Design Details
 
-Light validation done in `yarn prepack` to ensure that metadata is present and correct.
+_-_
 
 ### References & Prior Art
 
@@ -96,7 +142,7 @@ The following resources have been used to inform this proposal:
 
 ## Release Plan
 
-Assuming that the required fields can be populated with minimal effort
+TBD
 
 <!--
 This section should describe the rollout process for any new features. It must take our version policies into account and plan for a phased rollout if this change affects any existing stable APIs.
@@ -106,12 +152,16 @@ If there is any particular feedback to be gathered during the rollout, this shou
 
 ## Dependencies
 
+None
+
 <!--
 List any dependencies that this work has on other BEPs or features.
 -->
 
 ## Alternatives
 
+TBD
+
 <!--
 What other approaches did you consider, and why did you rule them out? These do
 not need to be as detailed as the proposal, but should include enough