From 9cd58092b90ae83b50c5ec61978f127c6490b334 Mon Sep 17 00:00:00 2001
From: Elliot Winkler <elliot.winkler@gmail.com>
Date: Tue, 22 Aug 2023 15:20:39 -0600
Subject: [PATCH 1/4] Publish preview builds to NPM instead of GitHub

Currently, when publishing core packages, we use NPM for "production"
releases but GitHub Package Registry for "preview" builds. This works to
keep the list of production versions free of clutter and mitigate the
risk of publishing preview builds as production releases accidentally,
but it also introduces a major pain point.

Usually in order to access a package with a preview build, the developer
must instruct Yarn to use GitHub Package Registry instead of NPM along
with an authentication token, and then update the version of the package
in the manifest to use the preview version. If, however, the package
introduces a new transitive dependency that is not available in preview
form, the developer must undo the changes to the Yarn configuration or
even temporarily add the dependency explicitly to the project in order
to fully install it. In some cases, these steps don't work at all.

To remove this pain point, this commit changes how preview builds are
published so that instead of using a separate registry, we use a
separate NPM scope. This preserves the separation between preview builds
and non-preview builds, and it means that the developer can mix
non-preview and preview versions in the manifest without needing to
reconfigure Yarn.
---
 .github/workflows/publish-preview.yml         |  2 -
 constraints.pro                               |  4 --
 package.json                                  |  4 +-
 packages/address-book-controller/package.json |  1 -
 packages/announcement-controller/package.json |  1 -
 packages/approval-controller/package.json     |  1 -
 packages/assets-controllers/package.json      |  1 -
 packages/base-controller/package.json         |  1 -
 packages/composable-controller/package.json   |  1 -
 packages/controller-utils/package.json        |  1 -
 packages/ens-controller/package.json          |  1 -
 packages/gas-fee-controller/package.json      |  1 -
 packages/keyring-controller/package.json      |  1 -
 packages/logging-controller/package.json      |  1 -
 packages/message-manager/package.json         |  1 -
 packages/network-controller/package.json      |  1 -
 packages/notification-controller/package.json |  1 -
 packages/permission-controller/package.json   |  1 -
 packages/phishing-controller/package.json     |  1 -
 packages/preferences-controller/package.json  |  1 -
 packages/rate-limit-controller/package.json   |  1 -
 packages/signature-controller/package.json    |  1 -
 packages/transaction-controller/package.json  |  1 -
 scripts/prepare-preview-builds.jq             | 54 +++++++++++++++++++
 scripts/prepare-preview-builds.sh             | 34 ++++++++++++
 scripts/prepare-preview-manifest.sh           | 34 ------------
 26 files changed, 90 insertions(+), 62 deletions(-)
 create mode 100644 scripts/prepare-preview-builds.jq
 create mode 100755 scripts/prepare-preview-builds.sh
 delete mode 100755 scripts/prepare-preview-manifest.sh

diff --git a/.github/workflows/publish-preview.yml b/.github/workflows/publish-preview.yml
index 3b74bd1bd6d..af9ac366136 100644
--- a/.github/workflows/publish-preview.yml
+++ b/.github/workflows/publish-preview.yml
@@ -40,8 +40,6 @@ jobs:
         with:
           node-version-file: '.nvmrc'
           cache: yarn
-          registry-url: 'https://npm.pkg.github.com'
-          scope: '@MetaMask'
       - run: yarn --immutable
       - name: Get commit SHA
         id: commit-sha
diff --git a/constraints.pro b/constraints.pro
index f8f64f6ad21..5d3f2f66f82 100644
--- a/constraints.pro
+++ b/constraints.pro
@@ -242,10 +242,6 @@ gen_enforced_field(WorkspaceCwd, 'files', []) :-
 gen_enforced_field(WorkspaceCwd, 'scripts.build:docs', 'typedoc') :-
   WorkspaceCwd \= '.'.
 
-% All published packages must have the same "prepare-manifest:preview" script.
-gen_enforced_field(WorkspaceCwd, 'scripts.prepare-manifest:preview', '../../scripts/prepare-preview-manifest.sh') :-
-  \+ workspace_field(WorkspaceCwd, 'private', true).
-
 % All published packages must have the same "publish:preview" script.
 gen_enforced_field(WorkspaceCwd, 'scripts.publish:preview', 'yarn npm publish --tag preview') :-
   \+ workspace_field(WorkspaceCwd, 'private', true).
diff --git a/package.json b/package.json
index 18d1bbb641a..7d4e35a9cc1 100644
--- a/package.json
+++ b/package.json
@@ -24,8 +24,8 @@
     "lint:fix": "yarn lint:eslint --fix && yarn lint:misc --write && yarn constraints --fix",
     "lint:misc": "prettier '**/*.json' '**/*.md' '!**/CHANGELOG.md' '!**/CHANGELOG.old.md' '**/*.yml' '!.yarnrc.yml' '!merged-packages/**' --ignore-path .gitignore",
     "prepack": "./scripts/prepack.sh",
-    "prepare-preview-builds": "yarn workspaces foreach --parallel run prepare-manifest:preview",
-    "publish-previews": "yarn workspaces foreach --parallel run publish:preview",
+    "prepare-preview-builds": "scripts/prepare-preview-builds.sh",
+    "publish-previews": "yarn workspaces foreach --parallel --verbose run publish:preview",
     "setup": "yarn install",
     "test": "yarn workspaces foreach --parallel --verbose run test"
   },
diff --git a/packages/address-book-controller/package.json b/packages/address-book-controller/package.json
index bcf44b06106..8e8d5f8a2b3 100644
--- a/packages/address-book-controller/package.json
+++ b/packages/address-book-controller/package.json
@@ -23,7 +23,6 @@
   "scripts": {
     "build:docs": "typedoc",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/address-book-controller",
-    "prepare-manifest:preview": "../../scripts/prepare-preview-manifest.sh",
     "publish:preview": "yarn npm publish --tag preview",
     "test": "jest",
     "test:watch": "jest --watch"
diff --git a/packages/announcement-controller/package.json b/packages/announcement-controller/package.json
index dbf8eb8fcac..bb76510f585 100644
--- a/packages/announcement-controller/package.json
+++ b/packages/announcement-controller/package.json
@@ -23,7 +23,6 @@
   "scripts": {
     "build:docs": "typedoc",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/announcement-controller",
-    "prepare-manifest:preview": "../../scripts/prepare-preview-manifest.sh",
     "publish:preview": "yarn npm publish --tag preview",
     "test": "jest",
     "test:watch": "jest --watch"
diff --git a/packages/approval-controller/package.json b/packages/approval-controller/package.json
index b9fc1231513..a1c1576bf8d 100644
--- a/packages/approval-controller/package.json
+++ b/packages/approval-controller/package.json
@@ -23,7 +23,6 @@
   "scripts": {
     "build:docs": "typedoc",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/approval-controller",
-    "prepare-manifest:preview": "../../scripts/prepare-preview-manifest.sh",
     "publish:preview": "yarn npm publish --tag preview",
     "test": "jest",
     "test:watch": "jest --watch"
diff --git a/packages/assets-controllers/package.json b/packages/assets-controllers/package.json
index e8526fdfb83..c62e4e64720 100644
--- a/packages/assets-controllers/package.json
+++ b/packages/assets-controllers/package.json
@@ -23,7 +23,6 @@
   "scripts": {
     "build:docs": "typedoc",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/assets-controllers",
-    "prepare-manifest:preview": "../../scripts/prepare-preview-manifest.sh",
     "publish:preview": "yarn npm publish --tag preview",
     "test": "jest",
     "test:watch": "jest --watch"
diff --git a/packages/base-controller/package.json b/packages/base-controller/package.json
index 16792ddd089..0f79c9b04c8 100644
--- a/packages/base-controller/package.json
+++ b/packages/base-controller/package.json
@@ -23,7 +23,6 @@
   "scripts": {
     "build:docs": "typedoc",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/base-controller",
-    "prepare-manifest:preview": "../../scripts/prepare-preview-manifest.sh",
     "publish:preview": "yarn npm publish --tag preview",
     "test": "jest",
     "test:watch": "jest --watch"
diff --git a/packages/composable-controller/package.json b/packages/composable-controller/package.json
index 8753c90ef45..83d82b16277 100644
--- a/packages/composable-controller/package.json
+++ b/packages/composable-controller/package.json
@@ -23,7 +23,6 @@
   "scripts": {
     "build:docs": "typedoc",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/composable-controller",
-    "prepare-manifest:preview": "../../scripts/prepare-preview-manifest.sh",
     "publish:preview": "yarn npm publish --tag preview",
     "test": "jest",
     "test:watch": "jest --watch"
diff --git a/packages/controller-utils/package.json b/packages/controller-utils/package.json
index 54c6541a449..6554e75eb43 100644
--- a/packages/controller-utils/package.json
+++ b/packages/controller-utils/package.json
@@ -23,7 +23,6 @@
   "scripts": {
     "build:docs": "typedoc",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/controller-utils",
-    "prepare-manifest:preview": "../../scripts/prepare-preview-manifest.sh",
     "publish:preview": "yarn npm publish --tag preview",
     "test": "jest",
     "test:watch": "jest --watch"
diff --git a/packages/ens-controller/package.json b/packages/ens-controller/package.json
index fa0c9e7318e..0ef14565b80 100644
--- a/packages/ens-controller/package.json
+++ b/packages/ens-controller/package.json
@@ -23,7 +23,6 @@
   "scripts": {
     "build:docs": "typedoc",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/ens-controller",
-    "prepare-manifest:preview": "../../scripts/prepare-preview-manifest.sh",
     "publish:preview": "yarn npm publish --tag preview",
     "test": "jest",
     "test:watch": "jest --watch"
diff --git a/packages/gas-fee-controller/package.json b/packages/gas-fee-controller/package.json
index 36b6c59e283..3f8da5c20e8 100644
--- a/packages/gas-fee-controller/package.json
+++ b/packages/gas-fee-controller/package.json
@@ -23,7 +23,6 @@
   "scripts": {
     "build:docs": "typedoc",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/gas-fee-controller",
-    "prepare-manifest:preview": "../../scripts/prepare-preview-manifest.sh",
     "publish:preview": "yarn npm publish --tag preview",
     "test": "jest",
     "test:watch": "jest --watch"
diff --git a/packages/keyring-controller/package.json b/packages/keyring-controller/package.json
index a2514ce3a67..81cbae774fb 100644
--- a/packages/keyring-controller/package.json
+++ b/packages/keyring-controller/package.json
@@ -23,7 +23,6 @@
   "scripts": {
     "build:docs": "typedoc",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/keyring-controller",
-    "prepare-manifest:preview": "../../scripts/prepare-preview-manifest.sh",
     "publish:preview": "yarn npm publish --tag preview",
     "test": "jest",
     "test:watch": "jest --watch"
diff --git a/packages/logging-controller/package.json b/packages/logging-controller/package.json
index 71f887ace10..d8be9f3ac66 100644
--- a/packages/logging-controller/package.json
+++ b/packages/logging-controller/package.json
@@ -23,7 +23,6 @@
   "scripts": {
     "build:docs": "typedoc",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/logging-controller",
-    "prepare-manifest:preview": "../../scripts/prepare-preview-manifest.sh",
     "publish:preview": "yarn npm publish --tag preview",
     "test": "jest",
     "test:watch": "jest --watch"
diff --git a/packages/message-manager/package.json b/packages/message-manager/package.json
index 0fca1ec939d..da862f2324b 100644
--- a/packages/message-manager/package.json
+++ b/packages/message-manager/package.json
@@ -23,7 +23,6 @@
   "scripts": {
     "build:docs": "typedoc",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/message-manager",
-    "prepare-manifest:preview": "../../scripts/prepare-preview-manifest.sh",
     "publish:preview": "yarn npm publish --tag preview",
     "test": "jest",
     "test:watch": "jest --watch"
diff --git a/packages/network-controller/package.json b/packages/network-controller/package.json
index ea38bbe2e15..2f76238f424 100644
--- a/packages/network-controller/package.json
+++ b/packages/network-controller/package.json
@@ -23,7 +23,6 @@
   "scripts": {
     "build:docs": "typedoc",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/network-controller",
-    "prepare-manifest:preview": "../../scripts/prepare-preview-manifest.sh",
     "publish:preview": "yarn npm publish --tag preview",
     "test": "jest",
     "test:watch": "jest --watch"
diff --git a/packages/notification-controller/package.json b/packages/notification-controller/package.json
index abaece27783..4812d392d39 100644
--- a/packages/notification-controller/package.json
+++ b/packages/notification-controller/package.json
@@ -23,7 +23,6 @@
   "scripts": {
     "build:docs": "typedoc",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/notification-controller",
-    "prepare-manifest:preview": "../../scripts/prepare-preview-manifest.sh",
     "publish:preview": "yarn npm publish --tag preview",
     "test": "jest",
     "test:watch": "jest --watch"
diff --git a/packages/permission-controller/package.json b/packages/permission-controller/package.json
index f8978e95fe5..98ba26a8a2f 100644
--- a/packages/permission-controller/package.json
+++ b/packages/permission-controller/package.json
@@ -23,7 +23,6 @@
   "scripts": {
     "build:docs": "typedoc",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/permission-controller",
-    "prepare-manifest:preview": "../../scripts/prepare-preview-manifest.sh",
     "publish:preview": "yarn npm publish --tag preview",
     "test": "jest",
     "test:watch": "jest --watch"
diff --git a/packages/phishing-controller/package.json b/packages/phishing-controller/package.json
index da871930f7a..ca778a73a39 100644
--- a/packages/phishing-controller/package.json
+++ b/packages/phishing-controller/package.json
@@ -23,7 +23,6 @@
   "scripts": {
     "build:docs": "typedoc",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/phishing-controller",
-    "prepare-manifest:preview": "../../scripts/prepare-preview-manifest.sh",
     "publish:preview": "yarn npm publish --tag preview",
     "test": "jest",
     "test:watch": "jest --watch"
diff --git a/packages/preferences-controller/package.json b/packages/preferences-controller/package.json
index 278ab5100aa..e99c24b225c 100644
--- a/packages/preferences-controller/package.json
+++ b/packages/preferences-controller/package.json
@@ -23,7 +23,6 @@
   "scripts": {
     "build:docs": "typedoc",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/preferences-controller",
-    "prepare-manifest:preview": "../../scripts/prepare-preview-manifest.sh",
     "publish:preview": "yarn npm publish --tag preview",
     "test": "jest",
     "test:watch": "jest --watch"
diff --git a/packages/rate-limit-controller/package.json b/packages/rate-limit-controller/package.json
index e7fffc7b81d..f147cb7cc32 100644
--- a/packages/rate-limit-controller/package.json
+++ b/packages/rate-limit-controller/package.json
@@ -23,7 +23,6 @@
   "scripts": {
     "build:docs": "typedoc",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/rate-limit-controller",
-    "prepare-manifest:preview": "../../scripts/prepare-preview-manifest.sh",
     "publish:preview": "yarn npm publish --tag preview",
     "test": "jest",
     "test:watch": "jest --watch"
diff --git a/packages/signature-controller/package.json b/packages/signature-controller/package.json
index eb4ec76979c..13419271ef2 100644
--- a/packages/signature-controller/package.json
+++ b/packages/signature-controller/package.json
@@ -23,7 +23,6 @@
   "scripts": {
     "build:docs": "typedoc",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/signature-controller",
-    "prepare-manifest:preview": "../../scripts/prepare-preview-manifest.sh",
     "publish:preview": "yarn npm publish --tag preview",
     "test": "jest",
     "test:watch": "jest --watch"
diff --git a/packages/transaction-controller/package.json b/packages/transaction-controller/package.json
index cffbbcda695..efb9aba78d0 100644
--- a/packages/transaction-controller/package.json
+++ b/packages/transaction-controller/package.json
@@ -23,7 +23,6 @@
   "scripts": {
     "build:docs": "typedoc",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/transaction-controller",
-    "prepare-manifest:preview": "../../scripts/prepare-preview-manifest.sh",
     "publish:preview": "yarn npm publish --tag preview",
     "test": "jest",
     "test:watch": "jest --watch"
diff --git a/scripts/prepare-preview-builds.jq b/scripts/prepare-preview-builds.jq
new file mode 100644
index 00000000000..68ec711000a
--- /dev/null
+++ b/scripts/prepare-preview-builds.jq
@@ -0,0 +1,54 @@
+# The name is overwritten, causing the package to get published under a
+# different NPM scope than non-preview builds. We do this so that the list of
+# non-preview builds does not get cluttered with noise and to prevent bad
+# versions from being published in case of a bug in the preview build process.
+.name |= sub("@metamask/"; "@metamask-previews/") |
+
+# The prerelease version is overwritten, preserving the non-prerelease portion
+# of the version. Technically we'd want to bump the non-prerelease portion as
+# well if we wanted this to be SemVer-compliant, but it was simpler not to.
+# This is just for testing, it doesn't need to strictly follow SemVer.
+.version |= split("-")[0] + "-preview.\($hash)" |
+
+# The workspace dependencies are updated to point to the exact preview build
+# version, so that Yarn does not try to resolve a different version from the
+# registry.
+
+if has("devDependencies") then
+  .devDependencies |= with_entries(
+    if .value | startswith("workspace:") then
+      .key |= sub("@metamask/"; "@metamask-previews/") |
+      .value |= sub("workspace:\\^"; "workspace:*")
+    else
+      .
+    end
+  )
+else
+  .
+end |
+
+if has("peerDependencies") then
+  .peerDependencies |= with_entries(
+    if .value | startswith("workspace:") then
+      .key |= sub("@metamask/"; "@metamask-previews/") |
+      .value |= sub("workspace:\\^"; "workspace:*")
+    else
+      .
+    end
+  )
+else
+  .
+end |
+
+if has("dependencies") then
+  .dependencies |= with_entries(
+    if .value | startswith("workspace:") then
+      .key |= sub("@metamask/"; "@metamask-previews/") |
+      .value |= sub("workspace:\\^"; "workspace:*")
+    else
+      .
+    end
+  )
+else
+  .
+end
diff --git a/scripts/prepare-preview-builds.sh b/scripts/prepare-preview-builds.sh
new file mode 100755
index 00000000000..33008f1604e
--- /dev/null
+++ b/scripts/prepare-preview-builds.sh
@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# This script prepares a package to be published as a preview build
+# to GitHub Packages.
+
+if [[ $# -eq 0 ]]; then
+  echo "Missing commit hash."
+  exit 1
+fi
+
+# We use the short commit hash as the prerelease version. This ensures each
+# preview build is unique and can be linked to a specific commit.
+shorthash="$1"
+
+prepare-preview-manifest() {
+  local manifest_file="$1"
+
+  # jq does not support in-place modification of files, so a temporary file is
+  # used to store the result of the operation. The original file is then
+  # overwritten with the temporary file.
+  jq --raw-output --arg hash "$shorthash" --from-file scripts/prepare-preview-builds.jq "$manifest_file" > temp.json
+  mv temp.json "$manifest_file"
+}
+
+echo "Preparing manifests..."
+while IFS=$'\t' read -r location name; do
+  echo "- $name"
+  prepare-preview-manifest "$location/package.json"
+done < <(yarn workspaces list --no-private --json | jq --slurp --raw-output 'map(select(.location != ".")) | map([.location, .name]) | map(@tsv) | .[]')
+
+echo "Installing dependencies..."
+yarn install --no-immutable
diff --git a/scripts/prepare-preview-manifest.sh b/scripts/prepare-preview-manifest.sh
deleted file mode 100755
index 95138bd20a0..00000000000
--- a/scripts/prepare-preview-manifest.sh
+++ /dev/null
@@ -1,34 +0,0 @@
-#!/usr/bin/env bash
-
-set -euo pipefail
-
-# This script prepares a package to be published as a preview build
-# to GitHub Packages.
-
-if [[ $# -eq 0 ]]; then
-  echo "Missing commit hash."
-  exit 1
-fi
-
-# We use the short commit hash as the prerelease version. This ensures each
-# preview build is unique and can be linked to a specific commit.
-shorthash="$1"
-
-# The prerelease version is overwritten, preserving the non-prerelease portion
-# of the version. Technically we'd want to bump the non-prerelease portion as
-# well if we wanted this to be SemVer-compliant, but it was simpler not to.
-# This is just for testing, it doesn't need to strictly follow SemVer.
-jq --raw-output --arg hash "$shorthash" '.version |= split("-")[0] + "-preview.\($hash)"' ./package.json |
-  # The workspace dependencies are updated to point to the exact preview build
-  # version, so that it does not try to resolve a different version from the
-  # registry.
-  jq --raw-output 'if has("devDependencies") then .devDependencies |= map_values(if . == "workspace:^" then "workspace:*" else . end) else . end' |
-  jq --raw-output 'if has("dependencies") then .dependencies |= map_values(if . == "workspace:^" then "workspace:*" else . end) else . end' |
-  # The registry is updated here because the manifest publish config always takes
-  # precedence, and cannot be overwritten from the command-line.
-  jq --raw-output ".publishConfig.registry = \"https://npm.pkg.github.com\"" > temp.json
-
-# jq does not support in-place modification of files, so a temporary file is
-# used to store the result of the first operation. The original file is then
-# overwritten with the temporary file.
-mv temp.json package.json

From d15734d3679514ec343a1c8776f933f60c33698c Mon Sep 17 00:00:00 2001
From: Elliot Winkler <elliot.winkler@gmail.com>
Date: Wed, 23 Aug 2023 12:21:08 -0600
Subject: [PATCH 2/4] Use relative paths

Co-authored-by: Mark Stacey <markjstacey@gmail.com>
---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 7d4e35a9cc1..381b97a545f 100644
--- a/package.json
+++ b/package.json
@@ -24,7 +24,7 @@
     "lint:fix": "yarn lint:eslint --fix && yarn lint:misc --write && yarn constraints --fix",
     "lint:misc": "prettier '**/*.json' '**/*.md' '!**/CHANGELOG.md' '!**/CHANGELOG.old.md' '**/*.yml' '!.yarnrc.yml' '!merged-packages/**' --ignore-path .gitignore",
     "prepack": "./scripts/prepack.sh",
-    "prepare-preview-builds": "scripts/prepare-preview-builds.sh",
+    "prepare-preview-builds": "./scripts/prepare-preview-builds.sh",
     "publish-previews": "yarn workspaces foreach --parallel --verbose run publish:preview",
     "setup": "yarn install",
     "test": "yarn workspaces foreach --parallel --verbose run test"

From 256826f28bb91883b28ccf5dc4a2a359c074d031 Mon Sep 17 00:00:00 2001
From: Elliot Winkler <elliot.winkler@gmail.com>
Date: Wed, 23 Aug 2023 13:29:28 -0600
Subject: [PATCH 3/4] Update contributing instructions

---
 docs/contributing.md | 79 +++++++++++++++-----------------------------
 1 file changed, 26 insertions(+), 53 deletions(-)

diff --git a/docs/contributing.md b/docs/contributing.md
index 071395a3056..ba8baa47b28 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -51,81 +51,54 @@ 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?
 
-## Using packages in other projects during development/testing
+## Testing changes to packages against another project
 
-When developing changes to packages within this repository that a different project depends upon, you may wish to load those changes into the project and test them locally or in CI before publishing proper releases of those packages. To solve that problem, this repository provides a mechanism to publish "preview" versions of packages to GitHub Package Registry. These versions can then be used in the project like any other version, provided the project is configured to use that registry.
+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.
 
 ### Publishing preview builds as a MetaMask contributor
 
-If you are a member of the MetaMask organization, you can create branches directly on this repository rather than using a fork. This allows you to use our preview build GitHub Action.
+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).
 
-Post a comment on the PR with the text `@metamaskbot publish-preview` (This triggers the `publish-preview` GitHub action). After a few minutes, you will see a new comment indicating that all packages have been published with the format `<package name>-<commit id>`.
+Note two things about each package:
 
-### Publishing preview builds as an independent contributor
-
-If you're a contributor and you've forked this repository, you can create preview versions for a branch by following these steps:
-
-1. Open the `package.json` for each package that you want to publish and change the scope in the name from `@metamask` to `@<your GitHub username>`.
-2. From your local fork of the repository, run `yarn prepare-preview-builds "$(git rev-parse --short HEAD)" && yarn build && yarn publish-previews` to generate preview versions for all packages based on the current branch and publish them to GitHub Package Registry.
-   - Take note of the version that is published; it should look like `1.2.3-e2df9b4` instead of `1.2.3`.
-
-### Using preview builds
+- 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`.
 
-> **Warning**
->
-> There is a known problem with the preview build workflow. It relies upon you having a local cache of any non-preview `@metamask/`-scoped packages.
->
-> If you encounter problems installing non-preview `@metamask/`-scoped packages when using this workflow, you can work around the problem by first installing dependencies without preview builds enabled (e.g. by temporarily removing the `.npmrc` or unsetting the required environment variables) to install the missing packages. Once they are installed, preview build installations should work (the non-preview `@metamask/`-scoped packages will be found in your local cache).
->
-> See [issue #1075](https://github.com/MetaMask/core/issues/1075) for more details.
+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`.
 
-Preview builds should automatically work in CI on the MetaMask extension and MetaMask mobile repositories, as long as the PR is in draft.
+### Publishing preview builds as an independent contributor
 
-To use preview builds locally, follow these steps:
+If you've forked this repository, you can create preview versions for a branch by following these steps:
 
-1. Navigate to your settings within GitHub and [create a classic access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-personal-access-token-classic). Make sure to give this token the `read:packages` scope.
-2. Follow these steps in the project using the preview builds:
+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).
 
-   - **Yarn 1 (classic) or NPM**
+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.
 
-     Add the following in `.npmrc`
+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`):
 
-     ```
-     @metamask:registry=https://npm.pkg.github.com
-     //npm.pkg.github.com/:_authToken=<your personal access token>
-     ```
+   ```
+   yarn prepare-preview-builds "@<NPM_ORG>" "$(git rev-parse --short HEAD)" && yarn build && yarn publish-previews
+   ```
 
-   - **Yarn >= 2 (berry):**
+   You should be able to see the published version of each package in the output. Note two things:
 
-     Ensure that the project `.yarnrc.yml` file has the following contents:
+   - 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`.
 
-     ```
-     npmRegistries:
-       "https://npm.pkg.github.com":
-         npmAlwaysAuth: true
-         npmAuthToken: "${GITHUB_NPM_TOKEN-}"
+4. Once this command is complete, all preview builds will be published, and you can then [use them in your project](#using-preview-builds).
 
-     npmScopes:
-       metamask:
-         npmRegistryServer: "${METAMASK_NPM_REGISTRY:-https://registry.yarnpkg.com}"
-     ```
+If you make more changes and wish to publish another set of preview builds, run steps 3 and 4 again.
 
-     The `METAMASK_NPM_REGISTRY` environment variable lets you control which registry is used for `@metamask`-scoped packages. Set this environment variable to `https://npm.pkg.github.com` to use preview builds. The `GITHUB_NPM_TOKEN` environment variable is where your token is set (the one created in step 1).
+### Using preview builds
 
-     For example, in Bash or ZSH, you can set both of these environment variables when installing dependencies:
+To use a preview build for a package within a project, open the project's `package.json`, find the dependency that corresponds to the package, and make two changes:
 
-     ```bash
-     GITHUB_NPM_TOKEN=<your personal access token> METAMASK_NPM_REGISTRY=https://npm.pkg.github.com yarn install
-     ```
+- Update `@metamask/` to `@metamask-previews/` (or whatever NPM scope you've chosen to publish under, if you've forked this monorepo)
+- Update the version to match a preview build (e.g. `1.2.3-e2df9b4` instead of `^1.2.3`)
 
-     - It's recommended to use your machine's local keychain to store the token, and retrieve it from there. For example on macOS, you can use:
-       ```bash
-       GITHUB_NPM_TOKEN=$(security find-generic-password -s 'GitHub NPM Token' -w) METAMASK_NPM_REGISTRY=https://npm.pkg.github.com yarn install
-       ```
+Finally, run `yarn install`.
 
-3. Update `package.json` with the new preview build versions
-   - Each preview build package should have a version matching (e.g. `1.2.3-e2df9b4` instead of `~1.2.3`), then run `yarn install`.
-4. Repeat step 3 each time you publish new preview builds.
+If you re-publish preview builds, make sure to return to the project's `package.json` and update the preview versions for the corresponding packages.
 
 ## Releasing
 

From 49b1c3f360d373faec30dc10bacff17771ef4356 Mon Sep 17 00:00:00 2001
From: Elliot Winkler <elliot.winkler@gmail.com>
Date: Wed, 23 Aug 2023 13:35:34 -0600
Subject: [PATCH 4/4] Allow NPM scope to be customized

---
 .github/workflows/publish-preview.yml | 2 +-
 scripts/prepare-preview-builds.jq     | 6 ++----
 scripts/prepare-preview-builds.sh     | 9 +++++++--
 3 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/publish-preview.yml b/.github/workflows/publish-preview.yml
index af9ac366136..df04fdf90f0 100644
--- a/.github/workflows/publish-preview.yml
+++ b/.github/workflows/publish-preview.yml
@@ -44,7 +44,7 @@ jobs:
       - name: Get commit SHA
         id: commit-sha
         run: echo "COMMIT_SHA=$(git rev-parse --short HEAD)" >> "$GITHUB_OUTPUT"
-      - run: yarn prepare-preview-builds ${{ steps.commit-sha.outputs.COMMIT_SHA }}
+      - run: yarn prepare-preview-builds @metamask-previews ${{ steps.commit-sha.outputs.COMMIT_SHA }}
       - run: yarn build
       - name: Publish preview build
         run: yarn publish-previews
diff --git a/scripts/prepare-preview-builds.jq b/scripts/prepare-preview-builds.jq
index 68ec711000a..b77d6fd2a9a 100644
--- a/scripts/prepare-preview-builds.jq
+++ b/scripts/prepare-preview-builds.jq
@@ -1,8 +1,6 @@
 # The name is overwritten, causing the package to get published under a
-# different NPM scope than non-preview builds. We do this so that the list of
-# non-preview builds does not get cluttered with noise and to prevent bad
-# versions from being published in case of a bug in the preview build process.
-.name |= sub("@metamask/"; "@metamask-previews/") |
+# different NPM scope than non-preview builds.
+.name |= sub("@metamask/"; "\($npm_scope)/") |
 
 # The prerelease version is overwritten, preserving the non-prerelease portion
 # of the version. Technically we'd want to bump the non-prerelease portion as
diff --git a/scripts/prepare-preview-builds.sh b/scripts/prepare-preview-builds.sh
index 33008f1604e..886fabafece 100755
--- a/scripts/prepare-preview-builds.sh
+++ b/scripts/prepare-preview-builds.sh
@@ -10,9 +10,14 @@ if [[ $# -eq 0 ]]; then
   exit 1
 fi
 
+# We don't want to assume that preview builds will be published alongside
+# "production" versions. There are security- and aesthetic-based advantages to
+# keeping them separate.
+npm_scope="$1"
+
 # We use the short commit hash as the prerelease version. This ensures each
 # preview build is unique and can be linked to a specific commit.
-shorthash="$1"
+shorthash="$2"
 
 prepare-preview-manifest() {
   local manifest_file="$1"
@@ -20,7 +25,7 @@ prepare-preview-manifest() {
   # jq does not support in-place modification of files, so a temporary file is
   # used to store the result of the operation. The original file is then
   # overwritten with the temporary file.
-  jq --raw-output --arg hash "$shorthash" --from-file scripts/prepare-preview-builds.jq "$manifest_file" > temp.json
+  jq --raw-output --arg npm_scope "$npm_scope" --arg hash "$shorthash" --from-file scripts/prepare-preview-builds.jq "$manifest_file" > temp.json
   mv temp.json "$manifest_file"
 }