docs/package-metadata: add section about metadata for published packages

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

docs/tooling/cli/02-build-system.md

@@ -617,7 +617,10 @@ A complete launch configuration for VS Code debugging may look like this:
 
 Package publishing is an optional part of the Backstage build system and not
 something you will need to worry about unless you are publishing packages to a
-registry. In order to publish a package, you first need to build it, which will
+registry. In addition to the documentation in the section, be sure to also read
+the section on [metadata for published packages](../package-metadata.md#metadata-for-published-packages).
+
+In order to publish a package, you first need to build it, which will
 populate the `dist` folder. Because the Backstage build system is optimized for
 local development along with our particular TypeScript and bundling setup, it is
 not possible to publish the package immediately at this point. This is because

docs/tooling/package-metadata.md

@@ -153,3 +153,38 @@ This field indicates that a package has been renamed and moved to a new location
   ...
 }
 ```
+
+## Metadata for Published Packages
+
+When publishing a package with the help of the Backstage CLI, there are a number of metadata checks that are performed to ensure that the package is correctly set up for the Backstage ecosystem. These checks are performed by the `backstage-cli package prepack` command, which is used to prepare a package for publishing. These checks can all also be verified separately using the `backstage-cli repo fix --publish` command, and in many cases the required metadata can be generated automatically. It is therefore important to make running the `fix` command part of your workflow in any project that is publishing Backstage packages.
+
+To set this up, we recommend that you add the following script to the root `package.json` of your workspace:
+
+```js
+{
+  "scripts": {
+    "fix": "backstage-cli repo fix --publish"
+  }
+}
+```
+
+This allows anyone working in the repo to run `yarn fix` to check and update all packages in the workspace.
+
+In addition, you should also add a check to your CI pipeline that ensures that there are no pending fixes. This is done by calling the command with the `--check` flag, which in GitHub actions would look something like this:
+
+```yaml
+- name: check for missing repo fixes
+  run: yarn fix --check
+```
+
+Finally, if you are using Husky or any other pre-commit hook, you can also set up a hook to run the fix command before committing:
+
+```js
+{
+  "lint-staged": {
+    "package.json": [
+      "yarn fix"
+    ]
+  }
+}
+```