-
-
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
5
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.
+251
−93
Open
Changes from all commits
Commits
Show all changes
5 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 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,204 @@ | ||
| # 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 are different instructions for using preview builds depending on whether the changes to a package you are testing are breaking or non-breaking. | ||
|
|
||
| ### Testing non-breaking changes to a package | ||
|
|
||
| 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]", | ||
| > ``` | ||
|
|
||
| ### Testing breaking changes to a package | ||
|
|
||
| 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]", | ||
| > ``` | ||
|
|
||
| ### Using a preview build for a patched package | ||
|
|
||
| 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: | ||
|
|
||
| ```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. | ||
|
|
||
| You will need to ensure that you keep the patch when you use a preview build for the package. 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" | ||
| > ``` | ||
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 |
|---|---|---|
| @@ -1,95 +1,8 @@ | ||
| # Testing changes to packages in other projects | ||
|
|
||
| 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. | ||
| 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)). | ||
|
|
||
| ### Testing changes to packages locally | ||
| There are two ways to do this: | ||
|
|
||
| If you're developing your project locally and want to test changes to a package, you can follow these steps: | ||
|
|
||
| 1. First, you must build the monorepo, by running `yarn build`. | ||
| 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. | ||
|
|
||
| 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: | ||
|
|
||
| ``` | ||
| "@metamask/<PACKAGE_NAME>@<PUBLISHED_VERSION_RANGE>": "file:<PATH_TO_CORE>/packages/<PACKAGE_NAME>" | ||
| ``` | ||
|
|
||
| > **Example:** | ||
| > | ||
| > - 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`: | ||
| > | ||
| > ``` | ||
| > "@metamask/controller-utils@^1.1.4": "file:../core/packages/controller-utils" | ||
| > ``` | ||
|
|
||
| 4. Run `yarn install`. | ||
|
|
||
| 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. | ||
|
|
||
| ### Testing changes to packages with preview builds | ||
|
|
||
| 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-preview-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 | ||
| ``` | ||
|
|
||
| You should be able to see the published version of each package in the output. Note two things: | ||
|
|
||
| - 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-preview-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 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 | ||
|
|
||
| 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: | ||
|
|
||
| 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. | ||
| 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 preview version on the right-hand side: | ||
|
|
||
| ``` | ||
| "@metamask/<PACKAGE_NAME>@<PRODUCTION_VERSION_RANGE>": "npm:@<NPM_ORG>/<PACKAGE_NAME>@<PREVIEW_VERSION>" | ||
| ``` | ||
|
|
||
| > **Example:** | ||
| > | ||
| > - 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`: | ||
| > | ||
| > ``` | ||
| > "@metamask/controller-utils@^1.1.4": "npm:@metamask-previews/[email protected]" | ||
| > ``` | ||
|
|
||
| 4. Run `yarn install`. | ||
| - [Preview builds](./preview-builds.md) _(recommended)_ | ||
| - [Local builds](./local-builds.md) |
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
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.