-
-
Notifications
You must be signed in to change notification settings - Fork 268
Update preview build instructions #7588
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
mcmire
wants to merge
7
commits into
main
Choose a base branch
from
update-preview-builds-instructions
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+283
−93
Open
Changes from all commits
Commits
Show all changes
7 commits
Select commit
Hold shift + click to select a range
a1327e2
Reorganize contributor docs
mcmire dc85193
Fix typo
mcmire 9d711b6
Merge branch 'main' into reorganize-docs
mcmire a04b461
Update preview build instructions
mcmire bc09a6a
Merge branch 'main' into update-preview-builds-instructions
mcmire 5463653
Simplify steps
mcmire b094486
Update section on patched dependencies
mcmire File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,41 @@ | ||
| # Using local builds | ||
|
|
||
| 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. | ||
|
|
||
| 1. First, build the monorepo by running `yarn build`. | ||
|
|
||
| 2. In the project, open `package.json` and locate the entry in `dependencies` for the package you want to test. | ||
|
|
||
| 3. Replace the version range in the right-hand side of the entry to point to the local build: | ||
|
|
||
| ```json | ||
| "@metamask/<PACKAGE_NAME>@<VERSION_RANGE>": "file:<PATH_TO_CORE>/packages/<PACKAGE_NAME>" | ||
| ``` | ||
|
|
||
| where: | ||
|
|
||
| - `PACKAGE_NAME` is the name of your package | ||
| - `VERSION_RANGE` is the version range of your package being used in production, usually starting with `^` | ||
| - `PATH_TO_MONOREPO` is the local path to the clone of this monorepo | ||
|
|
||
| 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.) | ||
|
|
||
| > **Example:** | ||
| > | ||
| > Given: | ||
| > | ||
| > - You have changes to `@metamask/controller-utils` you want to test | ||
| > - `@metamask/controller-utils` is listed at `^1.1.4` | ||
| > - You've cloned this repo next to the project | ||
| > | ||
| > In this case, you would go to `dependencies` and replace the line: | ||
| > | ||
| > ```json | ||
| > "@metamask/controller-utils": "^1.1.4" | ||
| > ``` | ||
| > | ||
| > with: | ||
| > | ||
| > ```json | ||
| > "@metamask/controller-utils@^1.1.4": "file:../core/packages/controller-utils" | ||
| > ``` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,236 @@ | ||
| # Publishing and using preview builds | ||
|
|
||
| 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. | ||
|
|
||
| Generally, when working with preview builds, you will follow this process: | ||
|
|
||
| 1. Create a branch in your clone of this repo | ||
| 2. Work on changes to your package(s) | ||
| 3. [Publish preview builds](#publishing-preview-builds) | ||
| 4. Switch to the project and [configure it to use the new preview builds](#using-preview-builds) | ||
| 5. Repeat steps 2-4 as necessary | ||
|
|
||
| ## Publishing preview builds | ||
|
|
||
| To publish preview builds: | ||
|
|
||
| 1. Create a pull request with the changes to your package(s). | ||
| 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. | ||
| 3. After a few minutes, you will see a new comment that lists the newly published packages along with their versions. | ||
|
|
||
| <details><summary><b>Publishing preview builds as an independent contributor</b></summary> | ||
| <br/> | ||
| 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: | ||
|
|
||
| 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). | ||
| 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. | ||
| 3. Run the following command to create and publish preview builds for all packages in the monorepo (replacing `NPM_ORG` as appropriate): | ||
|
|
||
| ```bash | ||
| yarn prepare-preview-builds "@<NPM_ORG>" "$(git rev-parse --short HEAD)" | ||
| yarn build | ||
| yarn publish-previews | ||
| ``` | ||
|
|
||
| You will see a list of the newly published packages along with their versions. | ||
| </details> | ||
|
|
||
| ## Using preview builds | ||
|
|
||
| To simulate production as best as possible, there two different paths to take depending on whether you anticipate making breaking or non-breaking changes to the package you want to test. | ||
|
|
||
| ### Testing non-breaking changes to a package | ||
|
|
||
| If you're in a MetaMask client repo (e.g. `metamask-extension` or `metamask-mobile`), run: | ||
|
|
||
| ```bash | ||
| yarn use-preview-build <name-of-package> <preview-version> --type non-breaking | ||
| ``` | ||
|
|
||
| For example: | ||
|
|
||
| ```bash | ||
| yarn use-preview-build @metamask/permission-controller 13.0.2-preview-940c934 --type non-breaking | ||
| ``` | ||
|
|
||
| <details> | ||
| <summary><strong>Manual steps</strong></summary> | ||
|
|
||
| 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: | ||
|
|
||
| 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. | ||
|
|
||
| 2. Run `yarn why @metamask/<PACKAGE_NAME>`, replacing `PACKAGE_NAME` as appropriate. You will see output like this: | ||
|
|
||
| ``` | ||
| ├─ @metamask/parent-controller-1@npm:93.1.0 | ||
| │ └─ @metamask/my-controller@npm:12.1.1 (via npm:^12.1.1) | ||
| │ | ||
| ├─ @metamask/parent-controller-2@npm:94.1.0 | ||
| │ └─ @metamask/my-controller@npm:12.1.1 (via npm:^12.1.1) | ||
| │ | ||
| ├─ @metamask/parent-controller-3@npm:94.1.0 [abc9d] | ||
| │ └─ @metamask/my-controller@npm:12.1.1 [57677] (via npm:^12.1.1 [15228]) | ||
| ... | ||
| │ | ||
| └─ metamask@workspace:. | ||
| └─ @metamask/my-controller@npm:12.1.1 [57677] (via npm:^12.1.0 [abc9d]) | ||
| ``` | ||
|
|
||
| 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`). | ||
|
|
||
| 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`. | ||
|
|
||
| 4. For each version range, add a new entry that looks like this: | ||
|
|
||
| ```json | ||
| "@metamask/<PACKAGE_NAME>@<VERSION_RANGE>": "npm:@<NPM_ORG>/<PACKAGE_NAME>@<PREVIEW_VERSION>" | ||
| ``` | ||
|
|
||
| where: | ||
|
|
||
| - `PACKAGE_NAME` is the name of your package | ||
| - `VERSION_RANGE` is one of the version ranges you noted in step 2 | ||
| - `NPM_ORG` is the NPM scope that the preview build is published under (note: this is _not_ `@metamask`) | ||
| - `PREVIEW_VERSION` is the version string of the preview build (note: this should _not_ start with `^`) | ||
|
|
||
| 5. Run `yarn install` to apply the changes. | ||
|
|
||
| 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. | ||
|
|
||
| > **Example:** | ||
| > | ||
| > - You have non-breaking changes to `@metamask/controller-utils` you want to test | ||
| > - You're in a MetaMask client repo | ||
| > - `@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 | ||
| > - You want to use the preview version `1.1.4-preview-e2df9b4` | ||
| > | ||
| > In this case, you would go to `resolutions` and add these lines: | ||
| > | ||
| > ```json | ||
| > "@metamask/controller-utils@^1.0.1": "npm:@metamask-previews/[email protected]", | ||
| > "@metamask/controller-utils@^1.1.3": "npm:@metamask-previews/[email protected]", | ||
| > "@metamask/controller-utils@^1.1.4": "npm:@metamask-previews/[email protected]", | ||
| > ``` | ||
| </details> | ||
|
|
||
| ### Testing breaking changes to a package | ||
|
|
||
| If you're in a MetaMask client repo (e.g. `metamask-extension` or `metamask-mobile`), run: | ||
|
|
||
| ```bash | ||
| yarn use-preview-build <name-of-package> <preview-version> --type breaking | ||
| ``` | ||
|
|
||
| For example: | ||
|
|
||
| ```bash | ||
| yarn use-preview-build @metamask/permission-controller 13.0.2-preview-940c934 --type breaking | ||
| ``` | ||
|
|
||
| <details> | ||
| <summary><strong>Manual steps</strong></summary> | ||
|
|
||
| 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: | ||
|
|
||
| 1. In the project, open `package.json`, and: | ||
|
|
||
| - Note the name of the package. | ||
| - 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`. | ||
|
|
||
| 2. Add a new entry that looks like this: | ||
|
|
||
| ```json | ||
| "<ROOT_PACKAGE_NAME>@workspace:./@metamask/<PACKAGE_NAME>": "npm:@<NPM_ORG>/<PACKAGE_NAME>@<PREVIEW_VERSION>" | ||
| ``` | ||
|
|
||
| where: | ||
|
|
||
| - `ROOT_PACKAGE_NAME` is the value of the `name` field at the top of `package.json` | ||
| - `NPM_ORG` is the NPM scope that the preview build is published under (note: this is _not_ `@metamask`) | ||
| - `PACKAGE_NAME` is the name of your package | ||
| - `PREVIEW_VERSION` is the version string of the preview build (note: this should _not_ start with `^`) | ||
|
|
||
| 3. Run `yarn install` to apply the changes. | ||
|
|
||
| > **Example:** | ||
| > | ||
| > - You have breaking changes to `@metamask/network-controller` you want to test | ||
| > - You're in a MetaMask client repo | ||
| > - The `name` in `package.json` is "metamask" | ||
| > - `@metamask/network-controller` is listed at `^12.4.9` | ||
| > - You want to use the preview version `12.4.9-preview-e2df9b4` | ||
| > | ||
| > In this case, you would go to `resolutions` and add this line: | ||
| > | ||
| > ```json | ||
| > "metamask@workspace:./@metamask/network-controller@^12.4.9": "npm:@metamask-previews/[email protected]", | ||
| > ``` | ||
| </details> | ||
|
|
||
| ### Using a preview build for a patched package | ||
|
|
||
| Sometimes the package you want to test is patched, and its entry in `dependencies` will look like this: | ||
|
|
||
| ```json | ||
| "@metamask/<PACKAGE_NAME>": "patch:@metamask/<PACKAGE_NAME>@npm:<ESCAPED_VERSION_RANGE>#~/.yarn/patches/<PATCH_NAME>.patch" | ||
| ``` | ||
|
|
||
| where: | ||
|
|
||
| - `PACKAGE_NAME` is the name of the package. | ||
| - `ESCAPED_VERSION_RANGE` is the version range, but where characters like `^` are escaped (for instance, `^` will appear as `%3A`). | ||
| - `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. | ||
|
|
||
| Note that at this time, the `use-preview-build` script mentioned above does not support patched dependencies. You will need to follow the manual steps, ensuring that you keep the patch when you add the resolution. To do this: | ||
|
|
||
| 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. | ||
|
|
||
| 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. | ||
|
|
||
| - 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). | ||
|
|
||
| > **Example 1 (non-breaking changes):** | ||
| > | ||
| > - You have non-breaking changes to `@metamask/controller-utils` you want to test | ||
| > - You're in a MetaMask client repo | ||
| > - `@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 | ||
| > - The dependency entry looks like this: | ||
| > ```json | ||
| > "@metamask/controller-utils": "patch:@metamask/controller-utils@npm%3A1.1.4#~/.yarn/patches/@metamask-controller-utils-npm-1.1.4-cccac388c7.patch" | ||
| > ``` | ||
| > - A resolution entry also exists which looks like this: | ||
| > ```json | ||
| > "@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" | ||
| > ``` | ||
| > - You want to use the preview version `1.1.4-preview-e2df9b4` | ||
| > | ||
| > In this case, you would go to `resolutions`, _remove_ the existing entry, and add these new entries: | ||
| > | ||
| > ```json | ||
| > "@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" | ||
| > "@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" | ||
| > "@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" | ||
| > ``` | ||
|
|
||
| > **Example 2 (breaking changes):** | ||
| > | ||
| > - You have breaking changes to `@metamask/network-controller` you want to test | ||
| > - You're in a MetaMask client repo | ||
| > - The `name` in `package.json` is "metamask" | ||
| > - `@metamask/network-controller` is listed at `^12.4.9` | ||
| > - The dependency entry looks like this: | ||
| > ```json | ||
| > "@metamask/network-controller": "patch:@metamask/network-controller@npm%3A12.4.9#~/.yarn/patches/@metamask-network-controller-npm-12.4.9-cccac388c7.patch" | ||
| > ``` | ||
| > - A resolution entry also exists which looks like this: | ||
| > ```json | ||
| > "@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" | ||
| > ``` | ||
| > - You want to use the preview version `12.4.9-preview-e2df9b4` | ||
| > | ||
| > In this case, you would go to `resolutions` and leave the existing one there, but _add_ a new one: | ||
| > | ||
| > ```json | ||
| > "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" | ||
| > ``` | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is a new process that I'm introducing in this PR. The previous process recommended that the engineer look at the existing dependency entry and target whatever version range was used there. Now I'm recommended that all version ranges in the dependency tree that are compatible with the one used in the dependency tree are targeted. As I mention at the top of this section, this is to mimic production as close as possible.
So on one hand, it's more accurate. On the other hand, it's more steps that before. Do we have any thoughts on this? It would nice if we could automate this somehow, but I'm not sure how to do that yet.