|
| 1 | +# Contributing to the monorepo |
| 2 | + |
| 3 | +## Getting started |
| 4 | + |
| 5 | +- Install [Node.js](https://nodejs.org) version 14. |
| 6 | + - If you're using [NVM](https://github.com/creationix/nvm#installation) (recommended), `nvm use` will ensure that the right version is installed. |
| 7 | +- Install [Yarn v3](https://yarnpkg.com/getting-started/install). |
| 8 | +- Run `yarn install` to install dependencies and run any required post-install scripts. |
| 9 | +- Run `yarn simple-git-hooks` to add a [Git hook](https://github.com/toplenboren/simple-git-hooks#what-is-a-git-hook) to your local development environment which will ensure that all files pass linting before you push a branch. |
| 10 | + |
| 11 | +## Testing |
| 12 | + |
| 13 | +- Run `yarn workspace <workspaceName> run test` to run all tests for a package. |
| 14 | +- Run `yarn workspace <workspaceName> run jest --no-coverage <file>` to run a test file within the context of a package. |
| 15 | +- Run `yarn test` to run tests for all packages. |
| 16 | + |
| 17 | +> **Note** |
| 18 | +> `workspaceName` in these commands is the `name` field within a package's `package.json`, e.g., `@metamask/address-book-controller`, not the directory where it is located, e.g., `packages/address-book-controller`. |
| 19 | +
|
| 20 | +## Using controllers in other projects during development/testing |
| 21 | + |
| 22 | +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. |
| 23 | + |
| 24 | +### As a MetaMask contributor |
| 25 | + |
| 26 | +If you're a MetaMask contributor, you can create these preview versions via draft pull requests: |
| 27 | + |
| 28 | +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 `packages:read` scope. |
| 29 | +2. Switch to your project locally and add a `.npmrc` file with the following content, filling in the appropriate areas: |
| 30 | + ``` |
| 31 | + @metamask:registry=https://npm.pkg.github.com |
| 32 | + //npm.pkg.github.com/:_authToken=<your personal access token> |
| 33 | + ``` |
| 34 | + Make sure not to commit this file. |
| 35 | +3. Go to GitHub and open up a pull request for this repository, then post a comment on the PR with the text `@metamask-bot preview-build`. (This triggers the `publish-preview` GitHub action.) |
| 36 | +4. After a few minutes, you will see a new comment indicating that all packages have been published with the format `<package name>-<commit id>`. |
| 37 | +5. Switch back to your project locally and update `package.json` by replacing the versions for the packages you've changed in your PR using the new version format (e.g. `1.2.3-e2df9b4` instead of `~1.2.3`), then run `yarn install`. |
| 38 | +6. Repeat steps 3-5 after pushing new changes to your PR to generate and use new preview versions. |
| 39 | + |
| 40 | +### As an independent contributor |
| 41 | + |
| 42 | +If you're a contributor and you've forked this repository, you can create preview versions for a branch via provided scripts: |
| 43 | + |
| 44 | +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 `packages:read` scope. |
| 45 | +2. Switch to your project locally and add a `.npmrc` file with the following content, filling in the appropriate areas: |
| 46 | + ``` |
| 47 | + @<your GitHub username>:registry=https://npm.pkg.github.com |
| 48 | + //npm.pkg.github.com/:_authToken=<your personal access token> |
| 49 | + ``` |
| 50 | + Make sure not to commit this file. |
| 51 | +3. 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>`. |
| 52 | +4. Switch to your fork of this repository locally and 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`. |
| 53 | +5. Switch back to your project and update `package.json` by replacing the versions for all packages you've changed using the version that was output in the previous step, then run `yarn install`. |
| 54 | +6. If you make any new changes to your project, repeat steps 3-5 to generate and use new preview versions. |
| 55 | +7. As changes will have been made to this repository (due to step 4), make sure to clear out those changes after you've completed testing. |
| 56 | + |
| 57 | +## Linting |
| 58 | + |
| 59 | +Run `yarn lint` to lint all files and show possible violations. |
| 60 | + |
| 61 | +Run `yarn lint:fix` to fix any automatically fixable violations. |
| 62 | + |
| 63 | +## Performing operations across the monorepo |
| 64 | + |
| 65 | +This repository relies on Yarn's [workspaces feature](https://yarnpkg.com/features/workspaces) to provide a way to work with packages individually and collectively. Refer to the documentation for the following Yarn commands for usage instructions: |
| 66 | + |
| 67 | +- [`yarn workspace`](https://yarnpkg.com/cli/workspace) |
| 68 | +- [`yarn workspaces foreach`](https://yarnpkg.com/cli/workspaces/foreach) |
| 69 | + |
| 70 | +> **Note** |
| 71 | +> |
| 72 | +> - `workspaceName` in the Yarn documentation is the `name` field within a package's `package.json`, e.g., `@metamask/address-book-controller`, not the directory where it is located, e.g., `packages/address-book-controller`. |
| 73 | +> - `commandName` in the Yarn documentation is any sub-command that the `yarn` executable would usually take. Pay special attention to the difference between `run` vs `exec`. If you want to run a package script, you would use `run`, e.g., `yarn workspace @metamask/address-book-controller run changelog:validate`; but if you want to run _any_ shell command, you'd use `exec`, e.g. `yarn workspace @metamask/address-book-controller exec cat package.json | jq '.version'`. |
| 74 | +
|
| 75 | +## Releasing |
| 76 | + |
| 77 | +The [`create-release-branch`](https://github.com/MetaMask/create-release-branch) tool and [`action-publish-release`](https://github.com/MetaMask/action-publish-release) GitHub action are used to automate the release process. |
| 78 | + |
| 79 | +1. **Create a release branch.** |
| 80 | + |
| 81 | + Run `yarn create-release-branch`. This tool generates a file and opens it in your editor, where you can specify which packages you want to include in the next release and which versions they should receive. Instructions are provided for you at the top; read them and update the file accordingly. |
| 82 | + |
| 83 | + When you're ready to continue, save and close the file. |
| 84 | + |
| 85 | +2. **Update changelogs for relevant packages.** |
| 86 | + |
| 87 | + At this point you will be on a new release branch, and a new section will have been added to the changelog of each package you specified in the previous step. |
| 88 | + |
| 89 | + For each changelog, review the new section and make the appropriate changes: |
| 90 | + |
| 91 | + - Move each entry into the appropriate category (review the ["Keep a Changelog"](https://keepachangelog.com/en/1.0.0/#types) spec for the full list of categories and the correct ordering of all categories). |
| 92 | + - Remove any changelog entries that don't affect consumers of the package (e.g. lockfile changes or development environment changes). Exceptions may be made for changes that might be of interest despite not having an effect upon the published package (e.g. major test improvements, security improvements, improved documentation, etc.). |
| 93 | + - Reword changelog entries to explain changes in terms that users of the package will understand (e.g., avoid referencing internal variables/concepts). |
| 94 | + - Consolidate related changes into one change entry if it makes it easier to comprehend. |
| 95 | + |
| 96 | + Run `yarn changelog:validate` to check that all changelogs are correctly formatted. |
| 97 | + |
| 98 | + Commit and push the branch. |
| 99 | + |
| 100 | +3. **Submit a pull request for the release branch so that it can be reviewed and tested.** |
| 101 | + |
| 102 | + Make sure the title of the pull request follows the pattern "Release \<new version\>". |
| 103 | + |
| 104 | + If changes are made to the base branch, the release branch will need to be updated with these changes and review/QA will need to restart again. As such, it's probably best to avoid merging other PRs into the base branch while review is underway. |
| 105 | + |
| 106 | +4. **"Squash & Merge" the release.** |
| 107 | + |
| 108 | + This step triggers the [`publish-release` GitHub action](https://github.com/MetaMask/action-publish-release) workflow to tag the final release commit and publish the release on GitHub. |
| 109 | + |
| 110 | + Pay attention to the box you see when you press the green button and ensure that the final name of the commit follows the pattern "Release \<new version\>". |
| 111 | + |
| 112 | +5. **Publish the release on NPM.** |
| 113 | + |
| 114 | + The `publish-release` GitHub Action workflow runs the `publish-npm` job, which publishes relevant packages to NPM. It requires approval from the [`npm-publishers`](https://github.com/orgs/MetaMask/teams/npm-publishers) team to complete. If you're not on the team, ask a member to approve it for you; otherwise, approve the job. |
| 115 | + |
| 116 | + Once the `publish-npm` job has finished, [check NPM](https://npms.io/search?q=scope%3Ametamask) to verify that all relevant packages has been published. |
0 commit comments