Backstage Yarn Plugin Docs adjustments

Signed-off-by: Andre Wanlin <awanlin@spotify.com>
2024-10-31 09:34:26 -05:00
parent 0d4baf3a23
commit 5819f8d5e1
4 changed files with 58 additions and 36 deletions
@@ -0,0 +1,5 @@
+---
+'@backstage/create-app': patch
+---
+
+Updated Dockerfile to include `backstage.json` file
@@ -85,6 +85,7 @@ WORKDIR /app
 # Copy files needed by Yarn
 COPY --chown=node:node .yarn ./.yarn
 COPY --chown=node:node .yarnrc.yml ./
+COPY --chown=node:node backstage.json ./

 # This switches many Node.js dependencies to production mode.
 ENV NODE_ENV=production
@@ -181,7 +182,7 @@ the repo root:
 FROM node:20-bookworm-slim AS packages

 WORKDIR /app
-COPY package.json yarn.lock ./
+COPY backstage.json package.json yarn.lock ./
 COPY .yarn ./.yarn
 COPY .yarnrc.yml ./

@@ -219,6 +220,7 @@ WORKDIR /app
 COPY --from=packages --chown=node:node /app .
 COPY --from=packages --chown=node:node /app/.yarn ./.yarn
 COPY --from=packages --chown=node:node /app/.yarnrc.yml  ./
+COPY --from=packages --chown=node:node /app/backstage.json ./

 RUN --mount=type=cache,target=/home/node/.cache/yarn,sharing=locked,uid=1000,gid=1000 \
    yarn install --immutable
@@ -266,7 +268,9 @@ WORKDIR /app
 # Copy the install dependencies from the build stage and context
 COPY --from=build --chown=node:node /app/.yarn ./.yarn
 COPY --from=build --chown=node:node /app/.yarnrc.yml  ./
+COPY --from=build --chown=node:node /app/backstage.json ./
 COPY --from=build --chown=node:node /app/yarn.lock /app/package.json /app/packages/backend/dist/skeleton/ ./
+
 # Note: The skeleton bundle only includes package.json files -- if your app has
 # plugins that define a `bin` export, the bin files need to be copied as well to
 # be linked in node_modules/.bin during yarn install.
@@ -9,41 +9,6 @@ latest releases. Backstage is more of a library than an application or service;
 similar to `create-react-app`, the `@backstage/create-app` tool gives you a
 starting point that's meant to be evolved.

-## Managing package versions with the Backstage yarn plugin
-
-The Backstage yarn plugin makes it easier to manage Backstage package versions,
-by determining the appropriate version for each package based on the overall
-Backstage version in backstage.json. This avoids the need to update every
-package.json across your Backstage monorepo, and means that when adding new
-`@backstage` dependencies, you don't need to worry about figuring out the right
-version to use to match the currently-installed release of Backstage.
-
-### Requirements
-
-In order to use the yarn plugin, you'll need to be using yarn 4.1.1 or greater.
-
-### Installation
-
-To install the yarn plugin, run the following command in your Backstage
-monorepo:
-
-```bash
-yarn plugin import https://versions.backstage.io/v1/tags/main/yarn-plugin
-```
-
-The resulting changes in the file system should be committed to your repo.
-
-### Usage
-
-When the yarn plugin is installed, versions for currently-released `@backstage`
-packages can be replaced in package.json with the string `"backstage:^"`. This
-instructs yarn to resolve the version based on the overall Backstage version in
-backstage.json.
-
-The `backstage-cli versions:bump` command documented below will detect the
-installation of the yarn plugin, and when it's installed, will automatically
-migrate dependencies across the monorepo to use it.
-
 ## Updating Backstage versions with backstage-cli

 The Backstage CLI has a command to bump all `@backstage` packages and
@@ -87,6 +52,53 @@ for any applicable updates when upgrading packages. As an alternative, the
 a consolidated view of all the changes between two versions of Backstage. You
 can find the current version of your Backstage installation in `backstage.json`.

+## Managing package versions with the Backstage yarn plugin
+
+The Backstage yarn plugin makes it easier to manage Backstage package versions,
+by determining the appropriate version for each package based on the overall
+Backstage version in backstage.json. This avoids the need to update every
+package.json across your Backstage monorepo, and means that when adding new
+`@backstage` dependencies, you don't need to worry about figuring out the right
+version to use to match the currently-installed release of Backstage.
+
+### Requirements
+
+In order to use the yarn plugin, you'll need to be using yarn 4.1.1 or greater.
+
+### Installation
+
+To install the yarn plugin, run the following command in your Backstage
+monorepo:
+
+```bash
+yarn plugin import https://versions.backstage.io/v1/tags/main/yarn-plugin
+```
+
+The resulting changes in the file system should be committed to your repo.
+
+:::tip
+
+For best results it's ideal to add the Backstage Yarn plugin when you are about to do a Backstage upgrade as it will make it easier to confirm everything is working.
+
+:::
+
+### Usage
+
+When the yarn plugin is installed, versions for currently-released `@backstage`
+packages can be replaced in package.json with the string `"backstage:^"`. This
+instructs yarn to resolve the version based on the overall Backstage version in
+`backstage.json`.
+
+:::tip
+
+The `backstage.json` is key for the plugin to work, make sure this file is included in your CI/CD pipelines and/or any Container builds.
+
+:::
+
+The `backstage-cli versions:bump` command documented above will detect the
+installation of the yarn plugin, and when it's installed, will automatically
+migrate dependencies across the monorepo to use it.
+
 ## More information on dependency mismatches

 Backstage is structured as a monorepo with
@@ -40,6 +40,7 @@ WORKDIR /app
 # Copy files needed by Yarn
 COPY --chown=node:node .yarn ./.yarn
 COPY --chown=node:node .yarnrc.yml ./
+COPY --chown=node:node backstage.json ./

 # This switches many Node.js dependencies to production mode.
 ENV NODE_ENV=production