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"],