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

docs: document installation and usage of yarn plugin

Browse Source 
Signed-off-by: MT Lewis <mtlewis@users.noreply.github.com>
This commit is contained in:
MT Lewis
2024-10-16 11:43:13 +01:00
parent d5652801eb
commit 98a1b5cf75
2 changed files with 50 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/getting-started/keeping-backstage-updated.md
+35
View File
@@ -9,6 +9,41 @@ 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.
## Managing package versions with the Backstage yarn plugin
The Backstage yarn plugin makes it easier to manage Backstage package versions,
by determining the appropriate version for each package based on the overall
Backstage version in backstage.json. This avoids the need to update every
package.json across your Backstage monorepo, and means that when adding new
`@backstage` dependencies, you don't need to worry about figuring out the right
version to use to match the currently-installed release of Backstage.
### Requirements
In order to use the yarn plugin, you'll need to be using yarn 4.1.1 or greater.
### Installation
To install the yarn plugin, run the following command in your Backstage
monorepo:
```bash
yarn plugin import https://versions.backstage.io/v1/tags/main/yarn-plugin
```
The resulting changes in the file system should be committed to your repo.
### Usage
When the yarn plugin is installed, versions for currently-released `@backstage`
packages can be replaced in package.json with the string `"backstage:^"`. This
instructs yarn to resolve the version based on the overall Backstage version in
backstage.json.
The `backstage-cli versions:bump` command documented below will detect the
installation of the yarn plugin, and when it's installed, will automatically
migrate dependencies across the monorepo to use it.
## Updating Backstage versions with backstage-cli
The Backstage CLI has a command to bump all `@backstage` packages and
packages/yarn-plugin/README.md
+15 -2
View File
@@ -9,5 +9,18 @@ version specified in the manifest for the Backstage release listed in
backstage.json. If the dependent package is published, this version will be
prefixed by `^`.
**This plugin is still under active development, and requires some further
testing before we recommend it for general use.**
Detailed instructions for using the plugin can be found in [the docs](https://backstage.io/docs/getting-started/keeping-backstage-updated/#managing-package-versions-with-the-backstage-yarn-plugin).
## Installation
```bash
yarn plugin import https://versions.backstage.io/v1/tags/main/yarn-plugin
```
The resulting changes in the file system should be committed to your repo.
## Usage
The yarn plugin recognizes the version string `"backstage:^"`, and replaces it
with the appropriate version based on the overall Backstage version in
backstage.json.