Use static versions for interdependencies (#1623)

If you have a project that depends on a package in this monorepo and you
want to test changes to the package locally, you cannot simply configure
that project to use a local reference to that package. Instead, you must
use a preview build of the package. While publishing that preview build
is a relatively easy process, getting the project to use that preview
build is not.

The reason why preview builds are needed is because of the way that
interdependencies work. If a package in the monorepo needs to depend on
another package in the monorepo, it uses `workspace:^` as the version.
Yarn, which understands the `workspace:` protocol, will resolve this
reference to the version of whatever the dependency package happens to
be when the dependent package is published.

But if no packages are published, such as the case when testing locally,
then `workspace:` references will never be resolved. If an attempt is
used to update the dependency on the package in question — let's say
`@metamask/base-controller` — by replacing the version with a `file:` or
`portal:` reference, Yarn will produce an error that looks like:

    ➤ YN0001: │ Error: @metamask/base-controller@workspace:^: Workspace not found (@metamask/base-controller@workspace:^)

To solve this problem, this commit replaces the `workspace:` references
with static references and adds a Yarn constraint to ensure that all
interdependencies match their actual versions. That is, if
`transaction-controller` depends on `base-controller`, then the version
it uses is guaranteed to match the version in `base-controller`'s
manifest.

constraints.pro

@@ -267,6 +267,14 @@ gen_enforced_dependency(WorkspaceCwd, DependencyIdent, 'a range optionally start
   workspace_has_dependency(WorkspaceCwd, DependencyIdent, DependencyRange, DependencyType),
   \+ is_valid_version_range(DependencyRange).
 
+% All references to a workspace package must be up to date with the current
+% version of that package.
+gen_enforced_dependency(WorkspaceCwd, DependencyIdent, CorrectDependencyRange, DependencyType) :-
+  workspace_has_dependency(WorkspaceCwd, DependencyIdent, DependencyRange, DependencyType),
+  workspace_ident(OtherWorkspaceCwd, DependencyIdent),
+  workspace_version(OtherWorkspaceCwd, OtherWorkspaceVersion),
+  atomic_list_concat(['^', OtherWorkspaceVersion], CorrectDependencyRange).
+
 % All dependency ranges for a package must be synchronized across the monorepo
 % (the least version range wins), regardless of which "*dependencies" field
 % where the package appears.

docs/contributing.md

@@ -51,30 +51,72 @@ When submitting a pull request for this repo, take some a bit of extra time to f
   - What are the anticipated effects to whichever platform might want to make use of these changes?
   - If there are breaking changes to the API, what do consumers need to do in order to adapt to those changes upon upgrading to them?
 
-## Testing changes to packages against another project
+## Testing changes to packages in another project
 
-If you have a project that depends on packages from this monorepo, you may wish to load changes to those packages into the project and test them locally or in CI before releasing them. To solve that problem, this repository provides a mechanism to publish "preview" versions of packages. These versions can then be used in the project like any other versions.
+If you have a project that depends on a package in this monorepo, you may want to load those changes into the project without having to create a whole new monorepo release. How you do this depends on your use case.
 
-### Publishing preview builds as a MetaMask contributor
+### Testing changes to packages locally
 
-If you're a member of the MetaMask organization, you can create preview builds for a pull request by posting a comment with the text `@metamaskbot publish-preview`. This starts the `publish-preview` GitHub action; after a few minutes, it should complete and you will see a new comment that lists the newly published packages. You can then [use these versions in your project](#using-preview-builds).
+If you're developing your project locally and want to test changes to a package, you can follow these steps:
 
-Note two things about each package:
+1. First, you must build the monorepo. It's recommend to run `yarn build:watch` so that changes to the package you want to change are reflected in your project automatically.
+2. Next, you need to connect the package to your project by overriding the resolution logic in your package manager to replace the published version of the package with the local version.
 
-- The name is scoped to `@metamask-previews` instead of `@metamask`.
-- The ID of the last commit in the branch is appended to the version, e.g. `1.2.3-e2df9b4` instead of `1.2.3`.
+   1. Open `package.json` in the project and locate the dependency entry for the package.
+   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 mirrors the dependency entry on the left-hand side and points to the local path on the right-hand side:
 
-If you make more changes and wish to publish another set of preview builds, post another comment on the pull request with `@metamaskbot publish-preview`.
+      ```
+      "@metamask/<PACKAGE_NAME>@<PUBLISHED_VERSION_RANGE>": "file:<PATH_TO_CORE>/packages/<PACKAGE_NAME>"
+      ```
 
-### Publishing preview builds as an independent contributor
+      > **Example:**
+      >
+      > - If you're a member of MetaMask, your project uses Yarn, `@metamask/controller-utils` is listed in dependencies at `^1.1.4`, and your clone of the `core` repo is at the same level as your project, add the following to `resolutions`:
+      >
+      >   ```
+      >   "@metamask/controller-utils@^1.1.4": "file:../core/packages/controller-utils"
+      >   ```
+      >
+      > - If you are an individual contributor, your project uses NPM, `@metamask/assets-controllers` is listed in dependencies at `^3.4.7`, and your fork of the `core` repo is at the same level as your project, add the following to `overrides`:
+      >
+      >   ```
+      >   "@metamask/assets-controllers@^3.4.7": "file:../core/packages/assets-controllers"
+      >   ```
 
-If you've forked this repository, you can create preview versions for a branch by following these steps:
+   4. Run `yarn install`.
 
-1. First, since preview build releases are published under an NPM organization, you'll need access to one. If this is not the case, you can either [create a new organization](https://www.npmjs.com/org/create) or [convert your existing username into an organization](https://www.npmjs.com/org/upgrade).
+3. Due to the use of Yarn's `file:` protocol, if you update the package in the monorepo, then you'll need to run `yarn install` in the project again.
 
-2. Once you've done this, open the `package.json` for each package that you want to publish and change the scope in the name from `@metamask` to `@<NPM_ORG>`, replacing `NPM_ORG` appropriately.
+### Testing changes to packages with preview builds
 
-3. Next, run the following commands to generate preview versions for all packages based on the current branch and publish them (again, replacing `NPM_ORG`):
+If you want to test changes to a package where it would be unwieldy or impossible to use a local version, such as on CI, you can publish a preview build and configure your project to use it.
+
+#### Publishing preview builds as a MetaMask contributor
+
+If you're a member of the MetaMask organization, you can create preview builds based on a pull request by following these steps:
+
+1. Post a comment on the pull request with the text `@metamaskbot publish-preview`. This starts the `publish-preview` GitHub action, which will create preview builds for all packages in the monorepo.
+2. After a few minutes, the action should complete and you will see a new comment that lists the newly published packages along with their versions.
+
+   Note two things about each package:
+
+   - The name is scoped to `@metamask-previews` instead of `@metamask`.
+   - The ID of the last commit in the branch is appended to the version, e.g. `1.2.3-e2df9b4` instead of `1.2.3`.
+
+Now you can [use these preview builds in your project](#using-preview-builds).
+
+If you make more changes to a package, follow step 2 again, making sure to update the reference to the package in your project's `package.json` to use the newly published preview version.
+
+#### Publishing preview builds as an independent contributor
+
+If you've forked this repository, you can create preview builds based on a branch by following these steps:
+
+1. First, since an NPM scope is used to host preview build releases, you'll need access to one. If you do not, you can either [create a new organization](https://www.npmjs.com/org/create) or [convert your existing username into an organization](https://www.npmjs.com/org/upgrade).
+
+2. Once you've done this, open the `package.json` for each package that you want to publish and change the scope in the name from `@metamask` to `@<NPM_ORG>`, replacing `NPM_ORG` with your NPM organization.
+
+3. Next, run the following command to create and publish the preview builds (again, replacing `NPM_ORG` as appropriate):
 
    ```
    yarn prepare-preview-builds "@<NPM_ORG>" "$(git rev-parse --short HEAD)" && yarn build && yarn publish-previews
@@ -85,11 +127,11 @@ If you've forked this repository, you can create preview versions for a branch b
    - The name is scoped to the NPM organization you entered instead of `@metamask`.
    - The ID of the last commit in the branch is appended to the version, e.g. `1.2.3-e2df9b4` instead of `1.2.3`.
 
-4. Once this command is complete, all preview builds will be published, and you can then [use them in your project](#using-preview-builds).
+Now you can [use these preview builds in your project](#using-preview-builds).
 
-If you make more changes and wish to publish another set of preview builds, run steps 3 and 4 again.
+If you make more changes to a package, follow step 3 again, making sure to update the reference to the package in your project's `package.json` to use the newly published preview version.
 
-### Using preview builds
+#### Using preview builds
 
 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:
 
@@ -98,24 +140,24 @@ To use a preview build for a package within a project, you need to override the
 3. Add a line to this section that mirrors the dependency entry on the left-hand side and points to the preview version on the right-hand side:
 
    ```
-   "@metamask/<PACKAGE_NAME>@<PRODUCTION_VERSION_SPECIFIER>": "npm:@<NPM_ORG>/<PACKAGE_NAME>@<PREVIEW_VERSION>"
+   "@metamask/<PACKAGE_NAME>@<PRODUCTION_VERSION_RANGE>": "npm:@<NPM_ORG>/<PACKAGE_NAME>@<PREVIEW_VERSION>"
    ```
 
-4. Run `yarn install`.
-
-For example:
+   > **Example:**
+   >
+   > - If you're a member of MetaMask, your project uses Yarn, `@metamask/controller-utils` is listed in dependencies at `^1.1.4`, and you want to use the preview version `1.2.3-e2df9b4`, add the following to `resolutions`:
+   >
+   >   ```
+   >   "@metamask/controller-utils@^1.1.4": "npm:@metamask-previews/controller-utils@1.2.3-e2df9b4"
+   >   ```
+   >
+   > - If you are an individual contributor, your project uses NPM, `@metamask/assets-controllers` is listed in dependencies at `^3.4.7`, and you want to use the preview version `4.5.6-bc2a997` published under `@foo`, add the following to `overrides`:
+   >
+   >   ```
+   >   "@metamask/assets-controllers@^3.4.7": "npm:@foo/assets-controllers@4.5.6-bc2a997"
+   >   ```
 
-- If you're a member of MetaMask, your project uses Yarn, `@metamask/controller-utils` is listed in dependencies at `^1.1.4`, and you want to use the preview version `1.2.3-e2df9b4`, add the following to `resolutions`:
-
-  ```
-  "@metamask/controller-utils@^1.1.4": "npm:@metamask-previews/controller-utils@1.2.3-e2df9b4"
-  ```
-
-- If you are an individual contributor, your project uses NPM, `@metamask/assets-controllers` is listed in dependencies at `^3.4.7`, and you want to use the preview version `4.5.6-bc2a997` published under `@foo`, add the following to `overrides`:
-
-  ```
-  "@metamask/assets-controllers@^3.4.7": "npm:@foo/assets-controllers@4.5.6-bc2a997"
-  ```
+4. Run `yarn install`.
 
 ## Releasing
 

packages/address-book-controller/package.json

@@ -28,8 +28,8 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@metamask/base-controller": "workspace:^",
-    "@metamask/controller-utils": "workspace:^",
+    "@metamask/base-controller": "^3.2.0",
+    "@metamask/controller-utils": "^4.3.1",
     "@metamask/utils": "^6.2.0"
   },
   "devDependencies": {

packages/announcement-controller/package.json

@@ -28,7 +28,7 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@metamask/base-controller": "workspace:^"
+    "@metamask/base-controller": "^3.2.0"
   },
   "devDependencies": {
     "@metamask/auto-changelog": "^3.1.0",

packages/approval-controller/package.json

@@ -28,7 +28,7 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@metamask/base-controller": "workspace:^",
+    "@metamask/base-controller": "^3.2.0",
     "@metamask/utils": "^6.2.0",
     "eth-rpc-errors": "^4.0.2",
     "immer": "^9.0.6",

packages/assets-controllers/package.json

@@ -33,14 +33,14 @@
     "@ethersproject/contracts": "^5.7.0",
     "@ethersproject/providers": "^5.7.0",
     "@metamask/abi-utils": "^2.0.1",
-    "@metamask/approval-controller": "workspace:^",
-    "@metamask/base-controller": "workspace:^",
+    "@metamask/approval-controller": "^3.5.0",
+    "@metamask/base-controller": "^3.2.0",
     "@metamask/contract-metadata": "^2.3.1",
-    "@metamask/controller-utils": "workspace:^",
+    "@metamask/controller-utils": "^4.3.1",
     "@metamask/eth-query": "^3.0.1",
     "@metamask/metamask-eth-abis": "3.0.0",
-    "@metamask/network-controller": "workspace:^",
-    "@metamask/preferences-controller": "workspace:^",
+    "@metamask/network-controller": "^12.1.1",
+    "@metamask/preferences-controller": "^4.3.0",
     "@metamask/rpc-errors": "^5.1.1",
     "@metamask/utils": "^6.2.0",
     "@types/uuid": "^8.3.0",
@@ -68,9 +68,9 @@
     "typescript": "~4.6.3"
   },
   "peerDependencies": {
-    "@metamask/approval-controller": "workspace:^",
-    "@metamask/network-controller": "workspace:^",
-    "@metamask/preferences-controller": "workspace:^"
+    "@metamask/approval-controller": "^3.5.0",
+    "@metamask/network-controller": "^12.1.1",
+    "@metamask/preferences-controller": "^4.3.0"
   },
   "engines": {
     "node": ">=16.0.0"

packages/composable-controller/package.json

@@ -28,7 +28,7 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@metamask/base-controller": "workspace:^"
+    "@metamask/base-controller": "^3.2.0"
   },
   "devDependencies": {
     "@metamask/auto-changelog": "^3.1.0",

packages/ens-controller/package.json

@@ -29,9 +29,9 @@
   },
   "dependencies": {
     "@ethersproject/providers": "^5.7.0",
-    "@metamask/base-controller": "workspace:^",
-    "@metamask/controller-utils": "workspace:^",
-    "@metamask/network-controller": "workspace:^",
+    "@metamask/base-controller": "^3.2.0",
+    "@metamask/controller-utils": "^4.3.1",
+    "@metamask/network-controller": "^12.1.1",
     "@metamask/utils": "^6.2.0",
     "ethereum-ens-network-map": "^1.0.2",
     "punycode": "^2.1.1"
@@ -47,7 +47,7 @@
     "typescript": "~4.6.3"
   },
   "peerDependencies": {
-    "@metamask/network-controller": "workspace:^"
+    "@metamask/network-controller": "^12.1.1"
   },
   "engines": {
     "node": ">=16.0.0"

packages/gas-fee-controller/package.json

@@ -28,10 +28,10 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@metamask/base-controller": "workspace:^",
-    "@metamask/controller-utils": "workspace:^",
+    "@metamask/base-controller": "^3.2.0",
+    "@metamask/controller-utils": "^4.3.1",
     "@metamask/eth-query": "^3.0.1",
-    "@metamask/network-controller": "workspace:^",
+    "@metamask/network-controller": "^12.1.1",
     "@metamask/utils": "^6.2.0",
     "@types/uuid": "^8.3.0",
     "ethereumjs-util": "^7.0.10",
@@ -54,7 +54,7 @@
     "typescript": "~4.6.3"
   },
   "peerDependencies": {
-    "@metamask/network-controller": "workspace:^"
+    "@metamask/network-controller": "^12.1.1"
   },
   "engines": {
     "node": ">=16.0.0"

packages/keyring-controller/package.json

@@ -29,10 +29,10 @@
   },
   "dependencies": {
     "@keystonehq/metamask-airgapped-keyring": "^0.13.1",
-    "@metamask/base-controller": "workspace:^",
+    "@metamask/base-controller": "^3.2.0",
     "@metamask/eth-keyring-controller": "^13.0.0",
-    "@metamask/message-manager": "workspace:^",
-    "@metamask/preferences-controller": "workspace:^",
+    "@metamask/message-manager": "^7.3.0",
+    "@metamask/preferences-controller": "^4.3.0",
     "@metamask/utils": "^6.2.0",
     "async-mutex": "^0.2.6",
     "ethereumjs-util": "^7.0.10",
@@ -57,7 +57,7 @@
     "uuid": "^8.3.2"
   },
   "peerDependencies": {
-    "@metamask/preferences-controller": "workspace:^"
+    "@metamask/preferences-controller": "^4.3.0"
   },
   "engines": {
     "node": ">=16.0.0"

packages/logging-controller/package.json

@@ -28,8 +28,8 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@metamask/base-controller": "workspace:^",
-    "@metamask/controller-utils": "workspace:^",
+    "@metamask/base-controller": "^3.2.0",
+    "@metamask/controller-utils": "^4.3.1",
     "uuid": "^8.3.2"
   },
   "devDependencies": {

packages/message-manager/package.json

@@ -28,8 +28,8 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@metamask/base-controller": "workspace:^",
-    "@metamask/controller-utils": "workspace:^",
+    "@metamask/base-controller": "^3.2.0",
+    "@metamask/controller-utils": "^4.3.1",
     "@metamask/eth-sig-util": "^6.0.0",
     "@metamask/utils": "^6.2.0",
     "@types/uuid": "^8.3.0",

packages/network-controller/package.json

@@ -28,8 +28,8 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@metamask/base-controller": "workspace:^",
-    "@metamask/controller-utils": "workspace:^",
+    "@metamask/base-controller": "^3.2.0",
+    "@metamask/controller-utils": "^4.3.1",
     "@metamask/eth-json-rpc-infura": "^8.1.1",
     "@metamask/eth-json-rpc-middleware": "^11.0.0",
     "@metamask/eth-json-rpc-provider": "^1.0.0",

packages/notification-controller/package.json

@@ -28,7 +28,7 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@metamask/base-controller": "workspace:^",
+    "@metamask/base-controller": "^3.2.0",
     "@metamask/utils": "^6.2.0",
     "immer": "^9.0.6",
     "nanoid": "^3.1.31"

packages/permission-controller/package.json

@@ -28,9 +28,9 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@metamask/approval-controller": "workspace:^",
-    "@metamask/base-controller": "workspace:^",
-    "@metamask/controller-utils": "workspace:^",
+    "@metamask/approval-controller": "^3.5.0",
+    "@metamask/base-controller": "^3.2.0",
+    "@metamask/controller-utils": "^4.3.1",
     "@metamask/utils": "^6.2.0",
     "@types/deep-freeze-strict": "^1.1.0",
     "deep-freeze-strict": "^1.1.1",
@@ -50,7 +50,7 @@
     "typescript": "~4.6.3"
   },
   "peerDependencies": {
-    "@metamask/approval-controller": "workspace:^"
+    "@metamask/approval-controller": "^3.5.0"
   },
   "engines": {
     "node": ">=16.0.0"

packages/phishing-controller/package.json

@@ -28,8 +28,8 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@metamask/base-controller": "workspace:^",
-    "@metamask/controller-utils": "workspace:^",
+    "@metamask/base-controller": "^3.2.0",
+    "@metamask/controller-utils": "^4.3.1",
     "@types/punycode": "^2.1.0",
     "eth-phishing-detect": "^1.2.0",
     "punycode": "^2.1.1"

packages/preferences-controller/package.json

@@ -28,8 +28,8 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@metamask/base-controller": "workspace:^",
-    "@metamask/controller-utils": "workspace:^"
+    "@metamask/base-controller": "^3.2.0",
+    "@metamask/controller-utils": "^4.3.1"
   },
   "devDependencies": {
     "@metamask/auto-changelog": "^3.1.0",

packages/rate-limit-controller/package.json

@@ -28,7 +28,7 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@metamask/base-controller": "workspace:^",
+    "@metamask/base-controller": "^3.2.0",
     "eth-rpc-errors": "^4.0.2",
     "immer": "^9.0.6"
   },