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

Update words, add versions:check section

Browse Source 
Signed-off-by: Tim Hansen <timbonicus@gmail.com>
This commit is contained in:
Tim Hansen
2021-03-05 09:31:36 -07:00
parent c694e47360
commit 2369c72cac
1 changed files with 43 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/getting-started/keeping-backstage-updated.md
+43 -12
View File
@@ -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
```