Skip to content

Commit a04b461

Browse files
mcmiremcmire
committed
Update preview build instructions
Preview builds are represented as prereleases, which means that care must be taken to accurately simulate what the dependency tree of a project will look like when a new production version is released. Unfortunately, the existing instructions for using preview builds do not achieve this. This problem has always existed but was exacerbated by the recent shift from peer dependencies to dependencies. This commit updates the instructions to fix these issues. There are now separate instructions for testing breaking changes vs. non-breaking changes. An addendum for working with patches, which was missing before, is also now included. Finally, instructions for using local builds has been split off from the preview builds instructions for ease of readability.
1 parent 9d711b6 commit a04b461

File tree

5 files changed

+251
-93
lines changed

5 files changed

+251
-93
lines changed

‎docs/processes/breaking-changes.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ For dependent packages located in `core`, you may get type errors immediately th
7373

7474
For other projects that live outside of `core`, you can use the following process to verify the effects:
7575

76-
1. Create a [preview build](./testing-changes-in-other-projects.md#testing-changes-to-packages-with-preview-builds) for your package.
76+
1. Create a [preview build](./preview-builds.md) for your package.
7777
2. Open draft PRs in the dependent projects.
7878
3. In each draft PR, upgrade your package to the preview build.
7979
4. Test the project, particularly the functionality that makes use of your package.

‎docs/processes/local-builds.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Using local builds
2+
3+
If you are unable to use [preview builds](./preview-builds.md) for testing, you can always build a package locally and link it to a project.
4+
5+
1. First, build the monorepo by running `yarn build`.
6+
7+
2. In the project, open `package.json` and locate the entry in `dependencies` for the package you want to test.
8+
9+
3. Replace the version range in the right-hand side of the entry to point to the local build:
10+
11+
```json
12+
"@metamask/<PACKAGE_NAME>@<VERSION_RANGE>": "file:<PATH_TO_CORE>/packages/<PACKAGE_NAME>"
13+
```
14+
15+
where:
16+
17+
- `PACKAGE_NAME` is the name of your package
18+
- `VERSION_RANGE` is the version range of your package being used in production, usually starting with `^`
19+
- `PATH_TO_MONOREPO` is the local path to the clone of this monorepo
20+
21+
4. Run `yarn install`. (Note that due to the use of Yarn's `file:` protocol, you'll need to repeat this step each time you update the package in the monorepo.)
22+
23+
> **Example:**
24+
>
25+
> Given:
26+
>
27+
> - You have changes to `@metamask/controller-utils` you want to test
28+
> - `@metamask/controller-utils` is listed at `^1.1.4`
29+
> - You've cloned this repo next to the project
30+
>
31+
> In this case, you would go to `dependencies` and replace the line:
32+
>
33+
> ```json
34+
> "@metamask/controller-utils": "^1.1.4"
35+
> ```
36+
>
37+
> with:
38+
>
39+
> ```json
40+
> "@metamask/controller-utils@^1.1.4": "file:../core/packages/controller-utils"
41+
> ```

‎docs/processes/preview-builds.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
# Publishing and using preview builds
2+
3+
Preview builds are pre-production versions of packages. Unlike [local builds](./local-builds.md), they are published to NPM (albeit under a separate NPM namespace) and can therefore be treated the same way as production releases in CI. Because of this, we recommend using preview builds for testing.
4+
5+
Generally, when working with preview builds, you will follow this process:
6+
7+
1. Create a branch in your clone of this repo
8+
2. Work on changes to your package(s)
9+
3. [Publish preview builds](#publishing-preview-builds)
10+
4. Switch to the project and [configure it to use the new preview builds](#using-preview-builds)
11+
5. Repeat steps 2-4 as necessary
12+
13+
## Publishing preview builds
14+
15+
To publish preview builds:
16+
17+
1. Create a pull request with the changes to your package(s).
18+
2. Post a comment on the pull request with the text `@metamaskbot publish-previews`. The `publish-preview` GitHub action will kick off to generate and publish preview builds for all packages in the monorepo.
19+
3. After a few minutes, you will see a new comment that lists the newly published packages along with their versions.
20+
21+
<details><summary><b>Publishing preview builds as an independent contributor</b></summary>
22+
<br/>
23+
Note that the steps above will only work if you are a member of the MetaMask engineering team on GitHub. If you are not, you'll need to follow some different steps:
24+
25+
1. First, you'll need access to an NPM organization under which the preview builds will be published. If you have not already done so, 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).
26+
2. Open the `package.json` for each package that you want to publish, and change the NPM scope in the package's name from `@metamask` to reflect your NPM organization.
27+
3. Run the following command to create and publish preview builds for all packages in the monorepo (replacing `NPM_ORG` as appropriate):
28+
29+
```bash
30+
yarn prepare-preview-builds "@<NPM_ORG>" "$(git rev-parse --short HEAD)"
31+
yarn build
32+
yarn publish-previews
33+
```
34+
35+
You will see a list of the newly published packages along with their versions.
36+
</details>
37+
38+
## Using preview builds
39+
40+
To simulate production as best as possible, there are different instructions for using preview builds depending on whether the changes to a package you are testing are breaking or non-breaking.
41+
42+
### Testing non-breaking changes to a package
43+
44+
If you have made non-breaking changes to the package you want to test, and therefore plan on bumping the _minor_ or _patch_ part of that package's version, follow these steps:
45+
46+
1. In the project, open `package.json` and locate the entry in `dependencies` for the package. Take note of the major part of the version.
47+
48+
2. Run `yarn why @metamask/<PACKAGE_NAME>`, replacing `PACKAGE_NAME` as appropriate. You will see output like this:
49+
50+
```
51+
├─ @metamask/parent-controller-1@npm:93.1.0
52+
│ └─ @metamask/my-controller@npm:12.1.1 (via npm:^12.1.1)
53+
│
54+
├─ @metamask/parent-controller-2@npm:94.1.0
55+
│ └─ @metamask/my-controller@npm:12.1.1 (via npm:^12.1.1)
56+
│
57+
├─ @metamask/parent-controller-3@npm:94.1.0 [abc9d]
58+
│ └─ @metamask/my-controller@npm:12.1.1 [57677] (via npm:^12.1.1 [15228])
59+
...
60+
│
61+
└─ metamask@workspace:.
62+
└─ @metamask/my-controller@npm:12.1.1 [57677] (via npm:^12.1.0 [abc9d])
63+
```
64+
65+
Take note of all the version ranges that match the major version you saw earlier (here, we are looking for all version ranges that start with `^12`).
66+
67+
3. Back in `package.json`, locate the section responsible for resolution overrides (or create one 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`.
68+
69+
4. For each version range, add a new entry that looks like this:
70+
71+
```json
72+
"@metamask/<PACKAGE_NAME>@<VERSION_RANGE>": "npm:@<NPM_ORG>/<PACKAGE_NAME>@<PREVIEW_VERSION>"
73+
```
74+
75+
where:
76+
77+
- `PACKAGE_NAME` is the name of your package
78+
- `VERSION_RANGE` is one of the version ranges you noted in step 2
79+
- `NPM_ORG` is the NPM scope that the preview build is published under (note: this is _not_ `@metamask`)
80+
- `PREVIEW_VERSION` is the version string of the preview build (note: this should _not_ start with `^`)
81+
82+
5. Run `yarn install` to apply the changes.
83+
84+
6. Run `yarn why @metamask/<PACKAGE_NAME>` again to confirm that all of the instances of the package you saw when you ran this command earlier are now using your preview build.
85+
86+
> **Example:**
87+
>
88+
> - You have non-breaking changes to `@metamask/controller-utils` you want to test
89+
> - You're in a MetaMask client repo
90+
> - `@metamask/controller-utils` is listed at `^1.1.4`, and `yarn why` reveals that `^1.0.1` and `^1.1.3` are also being used as version ranges in the dependency tree
91+
> - You want to use the preview version `1.1.4-preview-e2df9b4`
92+
>
93+
> In this case, you would go to `resolutions` and add these lines:
94+
>
95+
> ```json
96+
> "@metamask/controller-utils@^1.0.1": "npm:@metamask-previews/[email protected]",
97+
> "@metamask/controller-utils@^1.1.3": "npm:@metamask-previews/[email protected]",
98+
> "@metamask/controller-utils@^1.1.4": "npm:@metamask-previews/[email protected]",
99+
> ```
100+
101+
### Testing breaking changes to a package
102+
103+
If you have made breaking changes to the package you want to test, and therefore plan on bumping the _major_ part of that package's version, follow these steps:
104+
105+
1. In the project, open `package.json`, and:
106+
107+
- Note the name of the package.
108+
- Locate the section responsible for resolution overrides (or create one 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`.
109+
110+
2. Add a new entry that looks like this:
111+
112+
```json
113+
"<ROOT_PACKAGE_NAME>@workspace:./@metamask/<PACKAGE_NAME>": "npm:@<NPM_ORG>/<PACKAGE_NAME>@<PREVIEW_VERSION>"
114+
```
115+
116+
where:
117+
118+
- `ROOT_PACKAGE_NAME` is the value of the `name` field at the top of `package.json`
119+
- `NPM_ORG` is the NPM scope that the preview build is published under (note: this is _not_ `@metamask`)
120+
- `PACKAGE_NAME` is the name of your package
121+
- `PREVIEW_VERSION` is the version string of the preview build (note: this should _not_ start with `^`)
122+
123+
3. Run `yarn install` to apply the changes.
124+
125+
> **Example:**
126+
>
127+
> - You have breaking changes to `@metamask/network-controller` you want to test
128+
> - You're in a MetaMask client repo
129+
> - The `name` in `package.json` is "metamask"
130+
> - `@metamask/network-controller` is listed at `^12.4.9`
131+
> - You want to use the preview version `12.4.9-preview-e2df9b4`
132+
>
133+
> In this case, you would go to `resolutions` and add this line:
134+
>
135+
> ```json
136+
> "metamask@workspace:./@metamask/network-controller@^12.4.9": "npm:@metamask-previews/[email protected]",
137+
> ```
138+
139+
### Using a preview build for a patched package
140+
141+
When you go to add a resolution for a package you want to test following steps in either of the sections above, you may find that the package is patched. An entry for a patched dependency looks like this:
142+
143+
```json
144+
"@metamask/<PACKAGE_NAME>": "patch:@metamask/<PACKAGE_NAME>@npm:<ESCAPED_VERSION_RANGE>#~/.yarn/patches/<PATCH_NAME>.patch"
145+
```
146+
147+
where:
148+
149+
- `PACKAGE_NAME` is the name of the package.
150+
- `ESCAPED_VERSION_RANGE` is the version range, but where characters like `^` are escaped (for instance, `^` will appear as `%3A`).
151+
- `PATCH_NAME` is the filename for a patch. It is usually dash-separated, starts with the package name, and ends with the commit ID from which the patch was created.
152+
153+
You will need to ensure that you keep the patch when you use a preview build for the package. To do this:
154+
155+
1. Look for the escaped version range on the right-hand side of the dependency entry and mentally parse it to determine the underlying version range that the patch is being applied to.
156+
157+
2. When you add a resolution, target that version range on the left-hand side as if the patch were not there, and reuse the same `patch:` identifier on the right side, but replace the package name and version string accordingly.
158+
159+
- Note: Sometimes, for a patched dependency, the patch is present in not only as a dependency entry but also a resolution entry. If a resolution entry already exists, you'll want to replace it (but _only_ if you are making non-breaking changes, otherwise you'll want to add a new resolution).
160+
161+
> **Example 1 (non-breaking changes):**
162+
>
163+
> - You have non-breaking changes to `@metamask/controller-utils` you want to test
164+
> - You're in a MetaMask client repo
165+
> - `@metamask/controller-utils` is listed at `^1.1.4`, and `yarn why` reveals that `^1.0.1` and `^1.1.3` are also being used as version ranges in the dependency tree
166+
> - The dependency entry looks like this:
167+
> ```json
168+
> "@metamask/controller-utils": "patch:@metamask/controller-utils@npm%3A1.1.4#~/.yarn/patches/@metamask-controller-utils-npm-1.1.4-cccac388c7.patch"
169+
> ```
170+
> - A resolution entry also exists which looks like this:
171+
> ```json
172+
> "@metamask/controller-utils@npm:^1.1.4": "patch:@metamask/controller-utils@npm%3A1.1.4#~/.yarn/patches/@metamask-controller-utils-npm-1.1.4-cccac388c7.patch"
173+
> ```
174+
> - You want to use the preview version `1.1.4-preview-e2df9b4`
175+
>
176+
> In this case, you would go to `resolutions`, _remove_ the existing entry, and add these new entries:
177+
>
178+
> ```json
179+
> "@metamask/controller-utils@^1.0.1": "patch:@metamask-previews/controller-utils@npm%3A1.1.4-preview-e2df9b4#~/.yarn/patches/@metamask-controller-utils-npm-1.1.4-cccac388c7.patch"
180+
> "@metamask/controller-utils@^1.1.3": "patch:@metamask-previews/controller-utils@npm%3A1.1.4-preview-e2df9b4#~/.yarn/patches/@metamask-controller-utils-npm-1.1.4-cccac388c7.patch"
181+
> "@metamask/controller-utils@^1.1.4": "patch:@metamask-previews/controller-utils@npm%3A1.1.4-preview-e2df9b4#~/.yarn/patches/@metamask-controller-utils-npm-1.1.4-cccac388c7.patch"
182+
> ```
183+
184+
> **Example 2 (breaking changes):**
185+
>
186+
> - You have breaking changes to `@metamask/network-controller` you want to test
187+
> - You're in a MetaMask client repo
188+
> - The `name` in `package.json` is "metamask"
189+
> - `@metamask/network-controller` is listed at `^12.4.9`
190+
> - The dependency entry looks like this:
191+
> ```json
192+
> "@metamask/network-controller": "patch:@metamask/network-controller@npm%3A12.4.9#~/.yarn/patches/@metamask-network-controller-npm-12.4.9-cccac388c7.patch"
193+
> ```
194+
> - A resolution entry also exists which looks like this:
195+
> ```json
196+
> "@metamask/network-controller@npm:^12.4.9": "patch:@metamask/network-controller@npm%3A12.4.9#~/.yarn/patches/@metamask-network-controller-npm-12.4.9-cccac388c7.patch"
197+
> ```
198+
> - You want to use the preview version `12.4.9-preview-e2df9b4`
199+
>
200+
> In this case, you would go to `resolutions` and leave the existing one there, but _add_ a new one:
201+
>
202+
> ```json
203+
> "metamask@workspace:./@metamask/network-controller@^12.4.9": "patch:@metamask-previews/network-controller@npm%3A12.4.9-preview-e2df9b4#~/.yarn/patches/@metamask-network-controller-npm-12.4.9-cccac388c7.patch"
204+
> ```

‎docs/processes/testing-changes-in-other-projects.md‎

Lines changed: 4 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -1,95 +1,8 @@
11
# Testing changes to packages in other projects
22

3-
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.
3+
Often it is useful to test in-progress changes to one or more packages in the context of a project before releasing them (particularly when making [breaking changes](./breaking-changes.md)).
44

5-
### Testing changes to packages locally
5+
There are two ways to do this:
66

7-
If you're developing your project locally and want to test changes to a package, you can follow these steps:
8-
9-
1. First, you must build the monorepo, by running `yarn build`.
10-
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.
11-
12-
1. Open `package.json` in the project and locate the dependency entry for the package.
13-
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`.
14-
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:
15-
16-
```
17-
"@metamask/<PACKAGE_NAME>@<PUBLISHED_VERSION_RANGE>": "file:<PATH_TO_CORE>/packages/<PACKAGE_NAME>"
18-
```
19-
20-
> **Example:**
21-
>
22-
> - If 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`:
23-
>
24-
> ```
25-
> "@metamask/controller-utils@^1.1.4": "file:../core/packages/controller-utils"
26-
> ```
27-
28-
4. Run `yarn install`.
29-
30-
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.
31-
32-
### Testing changes to packages with preview builds
33-
34-
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.
35-
36-
#### Publishing preview builds as a MetaMask contributor
37-
38-
If you're a member of the MetaMask organization, you can create preview builds based on a pull request by following these steps:
39-
40-
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.
41-
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.
42-
43-
Note two things about each package:
44-
45-
- The name is scoped to `@metamask-previews` instead of `@metamask`.
46-
- The ID of the last commit in the branch is appended to the version, e.g. `1.2.3-preview-e2df9b4` instead of `1.2.3`.
47-
48-
Now you can [use these preview builds in your project](#using-preview-builds).
49-
50-
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.
51-
52-
#### Publishing preview builds as an independent contributor
53-
54-
If you've forked this repository, you can create preview builds based on a branch by following these steps:
55-
56-
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).
57-
58-
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.
59-
60-
3. Next, run the following command to create and publish the preview builds (again, replacing `NPM_ORG` as appropriate):
61-
62-
```
63-
yarn prepare-preview-builds "@<NPM_ORG>" "$(git rev-parse --short HEAD)" && yarn build && yarn publish-previews
64-
```
65-
66-
You should be able to see the published version of each package in the output. Note two things:
67-
68-
- The name is scoped to the NPM organization you entered instead of `@metamask`.
69-
- The ID of the last commit in the branch is appended to the version, e.g. `1.2.3-preview-e2df9b4` instead of `1.2.3`.
70-
71-
Now you can [use these preview builds in your project](#using-preview-builds).
72-
73-
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.
74-
75-
#### Using preview builds
76-
77-
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:
78-
79-
1. Open `package.json` in the project and locate the dependency entry for the core package for which you want to use a preview build.
80-
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`.
81-
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:
82-
83-
```
84-
"@metamask/<PACKAGE_NAME>@<PRODUCTION_VERSION_RANGE>": "npm:@<NPM_ORG>/<PACKAGE_NAME>@<PREVIEW_VERSION>"
85-
```
86-
87-
> **Example:**
88-
>
89-
> - If 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-preview-e2df9b4`, add the following to `resolutions`:
90-
>
91-
> ```
92-
> "@metamask/controller-utils@^1.1.4": "npm:@metamask-previews/[email protected]"
93-
> ```
94-
95-
4. Run `yarn install`.
7+
- [Preview builds](./preview-builds.md) _(recommended)_
8+
- [Local builds](./local-builds.md)

‎scripts/generate-preview-build-message.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ async function main(): Promise<void> {
3030
}
3131

3232
const previewBuildMessage = `
33-
Preview builds have been published. [See these instructions](https://github.com/MetaMask/core/blob/main/docs/processes/testing-changes-in-other-projects.md#testing-changes-to-packages-with-preview-builds) for more information about preview builds.
33+
Preview builds have been published. [See these instructions](https://github.com/MetaMask/core/blob/main/docs/processes/preview-builds.md) for more information about preview builds.
3434
3535
<details>
3636

0 commit comments

Comments
 (0)