yarn-plugin: support only "backstage:^"

Signed-off-by: MT Lewis <mtlewis@users.noreply.github.com>

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.**

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(

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)}`,
     );
   }
 

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'),
     );