From c694e473600130303684c69c8b534e48376ec239 Mon Sep 17 00:00:00 2001 From: Tim Hansen Date: Thu, 4 Mar 2021 19:45:12 -0700 Subject: [PATCH 1/2] Move the keeping-updated topic to getting-started Signed-off-by: Tim Hansen --- docs/FAQ.md | 21 ------------ .../keeping-backstage-updated.md | 33 +++++++++++++++++++ microsite/sidebars.json | 1 + 3 files changed, 34 insertions(+), 21 deletions(-) create mode 100644 docs/getting-started/keeping-backstage-updated.md diff --git a/docs/FAQ.md b/docs/FAQ.md index da10f9724c..c95e10ad4e 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -117,27 +117,6 @@ through the proxy. Learn more about [the different components](overview/what-is-backstage.md) that make up Backstage. -### How do I keep my Backstage app up to date? - -In many ways one can view Backstage as a library rather than an application or -service. The `@backstage/create-app` tool that is used to create your own -Backstage app is similar to -[`create-react-app`](https://github.com/facebook/create-react-app) in that it -gives you a starting point. The code you get is meant to be evolved, and most of -the functionality you get out of the box is brought in via npm dependencies. -Keeping your app up to date generally means keeping your dependencies up to -date. The Backstage CLI provides a command to help you with that. Simply run -`yarn backstage-cli versions:bump` at the root of your repo, and the latest -versions of all Backstage packages will be installed. - -While staying up to date with new releases and changes will keep your app up to -date, it can often be convenient to use the changes done to the -`@backstage/create-app` template as another method to stay up to date. For that -purpose, any changes done 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. - ### Why can't I dynamically install plugins without modifications the app? This decision is part of the core architecture and development flow of diff --git a/docs/getting-started/keeping-backstage-updated.md b/docs/getting-started/keeping-backstage-updated.md new file mode 100644 index 0000000000..5b3317d738 --- /dev/null +++ b/docs/getting-started/keeping-backstage-updated.md @@ -0,0 +1,33 @@ +--- +id: keeping-backstage-updated +title: Keeping Backstage Updated +description: How to keep your Backstage App updated +--- + +Backstage is always improving, so it's a good idea to stay in sync with the +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. + +## Updating Backstage versions with backstage-cli + +The Backstage CLI has a command to bump all `@backstage` packages you're using +to the latest versions: +[versions:bump](https://backstage.io/docs/cli/commands#versionsbump). + +```bash +npx 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. + +## Following @backstage/create-app 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 +[changelog](https://github.com/backstage/backstage/blob/master/packages/create-app/CHANGELOG.md) +of the `@backstage/create-app` package. diff --git a/microsite/sidebars.json b/microsite/sidebars.json index ffbdf0e383..d7ee3ebd80 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -32,6 +32,7 @@ "getting-started/deployment-other" ] }, + "getting-started/keeping-backstage-updated", "getting-started/contributors" ], "CLI": ["cli/index", "cli/commands"], From 2369c72cacd9bdd8bcabbb9e0c95ee8cb0e898b6 Mon Sep 17 00:00:00 2001 From: Tim Hansen Date: Fri, 5 Mar 2021 09:31:36 -0700 Subject: [PATCH 2/2] 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 +```