From 2369c72cacd9bdd8bcabbb9e0c95ee8cb0e898b6 Mon Sep 17 00:00:00 2001 From: Tim Hansen Date: Fri, 5 Mar 2021 09:31:36 -0700 Subject: [PATCH] Update words, add versions:check section Signed-off-by: Tim Hansen --- .../keeping-backstage-updated.md | 55 +++++++++++++++---- 1 file changed, 43 insertions(+), 12 deletions(-) diff --git a/docs/getting-started/keeping-backstage-updated.md b/docs/getting-started/keeping-backstage-updated.md index 5b3317d738..ffe4f4dcd5 100644 --- a/docs/getting-started/keeping-backstage-updated.md +++ b/docs/getting-started/keeping-backstage-updated.md @@ -11,23 +11,54 @@ starting point that's meant to be evolved. ## Updating Backstage versions with backstage-cli -The Backstage CLI has a command to bump all `@backstage` packages you're using -to the latest versions: +The Backstage CLI has a command to bump all `@backstage` packages and +dependencies you're using to the latest versions: [versions:bump](https://backstage.io/docs/cli/commands#versionsbump). ```bash -npx backstage-cli versions:bump +yarn backstage-cli versions:bump ``` -The reason for bumping all `@backstage` packages at once is dependency between -Backstage packages. React Context, for example, may not be referentially equal -if multiple versions of `@backstage/core` are loaded. +The reason for bumping all `@backstage` packages at once is to maintain the +dependencies that they have between each other. -## Following @backstage/create-app changes +## Following create-app template changes -Staying up to date with new releases will keep your app up to date, but there -can also be changes to the `@backstage/create-app` template that may be -beneficial. For that purpose, any changes made to the template are documented -along with upgrade instructions in the +The `@backstage/create-app` command creates the initial structure of your +Backstage installation from a **template**. The source of this template in the +Backstage repository is updated periodically, but your local `app` and `backend` +packages are established at `create-app` time and won't automatically get these +template updates. + +For this reason, any changes made to the template are documented along with +upgrade instructions in the [changelog](https://github.com/backstage/backstage/blob/master/packages/create-app/CHANGELOG.md) -of the `@backstage/create-app` package. +of the `@backstage/create-app` package. We recommend peeking at this changelog +for any applicable updates when upgrading packages. + +## More information on dependency mismatches + +Backstage is structured as a monorepo with +[Yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/). This means +the `app` and `backend` packages, as well as any custom plugins you've added, +are separate packages with their own `package.json` and dependencies. + +When a given dependency version is the _same_ between different packages, the +dependency is hoisted to the main `node_modules` folder in the monorepo root to +be shared between packages. When _different_ versions of the same dependency are +encountered, Yarn creates a `node_modules` folder within a particular package. + +This can lead to confusing situations with type definitions, or anything with +global state. React [Context](https://reactjs.org/docs/context.html), for +example, depends on global referential equality. This can cause problems in +Backstage with API lookup, or config loading. + +To help resolve these situations, the Backstage CLI has +[versions:check](https://backstage.io/docs/cli/commands#versionscheck). This +will validate versions of `@backstage` packages in your app to check for +duplicate definitions: + +```bash +# Add --fix to attempt automatic resolution in yarn.lock +yarn backstage-cli versions:check +```