Recommend focused resolutions for preview builds

When using a preview version, we don't want to replace the production
version across the dependency tree; we only really want to target its
direct usage by the project in question. This commit updates the
instructions for using preview builds to ensure that this happens by
asking the developer include a specific version on the left-hand side of
the resolution entry when updating `package.json`.

docs/contributing.md

@@ -91,28 +91,29 @@ If you make more changes and wish to publish another set of preview builds, run
 
 ### Using preview builds
 
-To effectively use a preview build for a package within a project, you need to override the resolution logic for your package manager so that the "production" version of that package is replaced with the preview version across the entire dependency tree.
+To use a preview build for a package within a project, you need to override the resolution logic for your package manager so that the "production" version of that package is replaced with the preview version. Here's how you do that:
 
-- If you're using Yarn, then you can use the `resolutions` field to accomplish this.
-- If you're using NPM or any other package manager, you can use the `overrides` field.
+1. Open `package.json` in the project and locate the current version of the package for which you want to use a preview build.
+2. Locate the section responsible for resolution overrides or create it if it doesn't exist. If you're using Yarn, this is `resolutions`; if you're using NPM or any other package manager, this is `overrides`.
+3. Add a line to this section that looks like this, replacing placeholders as appropriate:
 
-You will want to add a line to the appropriate section that looks like this, replacing placeholders:
+   ```
+   "@metamask/<PACKAGE_NAME>@^<PRODUCTION_VERSION>": "npm:@<NPM_ORG>/<PACKAGE_NAME>@<PREVIEW_VERSION>"
+   ```
 
-```
-"@metamask/<PACKAGE_NAME>": "npm:@<NPM_ORG>/<PACKAGE_NAME>@<VERSION>"
-```
+For example:
 
-For instance, if you're a member of MetaMask, your project uses Yarn, and you want to use a preview build of `@metamask/controller-utils` whose version is `1.2.3-e2df9b4`, you would add the following to `resolutions`:
+- If you're a member of MetaMask, your project uses Yarn, and you want to use a preview build of `@metamask/controller-utils` whose production version is `1.1.4` and whose preview version is `1.2.3-e2df9b4`, you would add the following to `resolutions`:
 
-```
-"@metamask/controller-utils": "npm:@metamask-previews/controller-utils@1.2.3-e2df9b4"
-```
+  ```
+  "@metamask/controller-utils@^1.1.4": "npm:@metamask-previews/controller-utils@1.2.3-e2df9b4"
+  ```
 
-And if you are an individual contributor, your project uses NPM, and you want to use a preview build of `@metamask/assets-controllers` published under `@foo` whose version is `4.5.6-bc2a997`, you would add the following to `overrides`:
+- If you are an individual contributor, your project uses NPM, and you want to use a preview build of `@metamask/assets-controllers` published under `@foo` whose production version is `3.4.7` and whose preview version is `4.5.6-bc2a997`, you would add the following to `overrides`:
 
-```
-"@metamask/assets-controllers": "npm:@foo/assets-controllers@4.5.6-bc2a997"
-```
+  ```
+  "@metamask/assets-controllers@^3.4.7": "npm:@foo/assets-controllers@4.5.6-bc2a997"
+  ```
 
 ## Releasing