paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 20 Packages Projects Releases Wiki Activity

Merge pull request #27414 from awanlin/docs/yarn-plugin-adjustments

Browse Source 
Backstage Yarn Plugin Docs adjustments
This commit is contained in:
Andre Wanlin
2024-11-20 13:00:36 -06:00
committed by GitHub
parent 7d8777dbba d97655487a
commit 6e6db67d2f
4 changed files with 64 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/deployment/docker.md
+5 -1
View File
@@ -88,6 +88,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
@@ -184,7 +185,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 ./
@@ -222,6 +223,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
@@ -269,7 +271,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.
docs/getting-started/keeping-backstage-updated.md
+53 -35
View File
@@ -17,41 +17,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
@@ -65,6 +30,12 @@ yarn backstage-cli versions:bump
The reason for bumping all `@backstage` packages at once is to maintain the
dependencies that they have between each other.
:::tip
To make the the version bump process even easier and more streamlined we highly recommend using the [Backstage yarn plugin](#managing-package-versions-with-the-backstage-yarn-plugin)
:::
By default the bump command will upgrade `@backstage` packages to the latest `main` release line which is released monthly. For those in a hurry that want to track the `next` release line which releases weekly can do so using the `--release next` option.
```bash
@@ -95,6 +66,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