Merge pull request #4826 from backstage/timbonicus/keep-updated

Move the keeping-updated topic to getting-started

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

docs/getting-started/keeping-backstage-updated.md

@@ -0,0 +1,64 @@
+---
+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 and
+dependencies you're using to the latest versions:
+[versions:bump](https://backstage.io/docs/cli/commands#versionsbump).
+
+```bash
+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.
+
+## Following create-app template changes
+
+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. 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
+```

microsite/sidebars.json

@@ -32,6 +32,7 @@
           "getting-started/deployment-other"
         ]
       },
+      "getting-started/keeping-backstage-updated",
       "getting-started/contributors"
     ],
     "CLI": ["cli/index", "cli/commands"],