diff --git a/packages/yarn-plugin/README.md b/packages/yarn-plugin/README.md index dc3e509872..16507713af 100644 --- a/packages/yarn-plugin/README.md +++ b/packages/yarn-plugin/README.md @@ -1,12 +1,13 @@ # yarn-plugin-backstage This yarn plugin adds a `backstage:` version protocol to yarn, which replaces -specific version ranges for `@backstage/` packages. The recommended mode of use -is to set all versions strings to `backstage:*` in package.json, which causes -all versions to be resolved based on the version of Backstage specified in -`backstage.json`. This ensures that all `@backstage/` packages always correspond -to a single release, and removes the need for `package.json` files -to change when upgrading to a new release. +specific version ranges for `@backstage/` packages. The only version range +supported by this plugin is `backstage:^`, which has similar semantics to the +corresponding [`workspace` range](https://yarnpkg.com/features/workspaces#cross-references) when using +workspace dependencies; locally, the package will always resolve to the exact +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.** diff --git a/packages/yarn-plugin/src/handlers/beforeWorkspacePacking.ts b/packages/yarn-plugin/src/handlers/beforeWorkspacePacking.ts index 80e663f17f..a98e8270a1 100644 --- a/packages/yarn-plugin/src/handlers/beforeWorkspacePacking.ts +++ b/packages/yarn-plugin/src/handlers/beforeWorkspacePacking.ts @@ -45,10 +45,7 @@ export const beforeWorkspacePacking = async ( ] as const) { const entries = Array.from( workspace.manifest.getForScope(dependencyType).values(), - ).filter( - descriptor => - structUtils.parseRange(descriptor.range).protocol === PROTOCOL, - ); + ).filter(descriptor => descriptor.range === `${PROTOCOL}^`); for (const descriptor of entries) { const finalDependencyType = getFinalDependencyType( diff --git a/packages/yarn-plugin/src/resolver/BackstageResolver.ts b/packages/yarn-plugin/src/resolver/BackstageResolver.ts index 2bb16f8525..61fbdab58e 100644 --- a/packages/yarn-plugin/src/resolver/BackstageResolver.ts +++ b/packages/yarn-plugin/src/resolver/BackstageResolver.ts @@ -35,7 +35,7 @@ export class BackstageResolver implements Resolver { bindDescriptor(descriptor: Descriptor): Descriptor { return structUtils.makeDescriptor( descriptor, - `backstage:${inferBackstageVersion(descriptor)}`, + `${PROTOCOL}${inferBackstageVersion(descriptor)}`, ); } diff --git a/packages/yarn-plugin/src/util.ts b/packages/yarn-plugin/src/util.ts index 25b760982b..ae11019c66 100644 --- a/packages/yarn-plugin/src/util.ts +++ b/packages/yarn-plugin/src/util.ts @@ -31,8 +31,8 @@ export const inferBackstageVersion = (descriptor: Descriptor) => { let selector = range.selector; - // For backstage:* we look up the version from backstage.json - if (selector === `*`) { + // For backstage:^ we look up the version from backstage.json + if (selector === `^`) { const backstageJson = xfs.readJsonSync( npath.toPortablePath('./backstage.json'), );