You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Those of us that have worked on the monorepo have a lot of context
around why it exists, what it does, and how to work with it, but
for everyone else, this context may not exist. The set of guides in this
commit aims to fill in the missing gaps. I've also included a bit around
preview builds at the end. We may also need an expanded section on
creating new releases, as people may not immediately jump to the docs
for `create-release-branch`, and those docs may not be as comprehensive
as they could be. This could come in a future PR, however.
Here is a graph that shows the dependencies among all packages:
29
+
Or, in graph form:
30
30
31
31
32
32
33
33
> **Note**
34
34
> To regenerate this graph, run `yarn generate-dependency-graph`.
35
35
36
+
## Architecture
37
+
38
+
This is a monorepo that houses multiple packages published under the `@metamask` namespace on NPM. Here are some topics you may find useful when developing:
39
+
40
+
-[What is a controller and how are they used?](docs/what.md)
41
+
-[Why we're using a monorepo](docs/why.md)
42
+
-[How the monorepo works](docs/how.md)
43
+
-[Common tasks you may need to perform when working on a package](docs/common-tasks.md)
44
+
-[How to test in-progress changes to a package within a project](docs/preview-builds.md)
45
+
36
46
## Contributing
37
47
38
48
### Setup
@@ -41,17 +51,17 @@ Here is a graph that shows the dependencies among all packages:
41
51
- If you are using [nvm](https://github.com/creationix/nvm#installation) (recommended) running `nvm use` will automatically choose the right node version for you.
- Run `yarn install` to install dependencies and run any required post-install scripts.
44
-
- Run `yarn simple-git-hooks` to add a [Git hook](https://github.com/toplenboren/simple-git-hooks#what-is-a-git-hook) which will ensure that all files pass the linter before you push a branch.
54
+
- 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 the linter before you push a branch.
45
55
46
56
### Testing and Linting
47
57
48
-
Run `yarn test` to run tests for all packages. Run `yarn workspace <package-name> run test` to run tests for a single package.
58
+
Run `yarn test` to run tests for all packages. Run `yarn workspace <package-name> run test` to run tests for a single package (where `<package-name>` is the published name of a package, e.g. `@metamask/announcement-controller`, not its location within the monorepo, e.g. `packages/announcement-controller`).
49
59
50
60
Run `yarn lint` to lint all files and show possible violations, or run `yarn lint:fix` to fix any automatically fixable violations.
51
61
52
62
### Release & Publishing
53
63
54
-
This project follows a unique release process. 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; see those repositories for more information about how they work.
64
+
This project follows a process which is unique to this repo. 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; see those repositories for more information about how they work.
55
65
56
66
1. To begin the release process, run `create-release-branch`, specifying the packages you want to release. This tool will bump versions and update changelogs across the monorepo automatically, then create a new branch for you.
When working with the monorepo, you will always be concerned with one of two needs:
4
+
5
+
- How do I do something for only one package?
6
+
- How do I do the same thing across all packages?
7
+
8
+
If you've read the ["How"](./how.md) section you know that we can use Yarn for both of these, because it treats the monorepo as a workspace of workspaces.
9
+
10
+
## Doing something for only one package
11
+
12
+
Use `yarn workspace <package> <rest...>`.
13
+
14
+
That `package` argument is important: it's the name of the package you want to target, not the directory where the package is located.
15
+
16
+
As for the `rest`, it depends on what you want to do:
17
+
18
+
- If you want to run a package script (a command configured under the package's `scripts` field) or an executable (a command that a dependency provides), use `run` followed by the name of the script and the arguments.
19
+
- If you want to run an arbitrary command, use `exec` followed by the name of the command and the arguments.
20
+
21
+
### Examples
22
+
23
+
We'll assume you're working with the package `@metamask/address-book-controller`:
24
+
25
+
If you want to use the package script `test` to run all tests:
26
+
27
+
```
28
+
yarn workspace @metamask/address-book-controller run test
29
+
```
30
+
31
+
If you want to use the `jest` executable to run Jest directly instead:
32
+
33
+
```
34
+
yarn workspace @metamask/address-book-controller run jest
35
+
```
36
+
37
+
If you want to read `package.json` and run it through `jq` to grab the current version:
Use `yarn workspaces foreach <rest...>` (notice the `s`).
46
+
47
+
As with `yarn workspace`, it depends on what you want to do:
48
+
49
+
- If you want to run a package script, use `run` followed by the name of the script and the arguments.
50
+
- If you want to run an arbitrary command, use `exec` followed by the name of the command and the arguments.
51
+
52
+
This command takes a bunch of options, but these are the ones we've found useful:
53
+
54
+
-`--verbose` is practically necessary, because without it, you won't know which part of the output came from which package.
55
+
-`--parallel` will run the command across a set pool of packages at the same time. This can be handy for speeding up your run.
56
+
-`--topological` / `--topological-dev` is neat because it will sort packages in dependency order. This means that the command will run first for packages that do not depend on any other packages, then it will run the command for all of the packages that depend on those packages, etc. (The `-dev` variant includes `devDependencies` when determining what a package's dependencies are, otherwise they are ignored.)
57
+
58
+
### Examples
59
+
60
+
If you want to use the package script `test` to run all tests across all packages (note: the `yarn test` command does this already):
61
+
62
+
```
63
+
yarn workspaces foreach --verbose test
64
+
```
65
+
66
+
If you want to use the `jest` executable to run Jest directly for all packages:
67
+
68
+
```
69
+
yarn workspaces foreach --verbose run jest
70
+
```
71
+
72
+
If you want to read `package.json` and run it through `jq` to grab the current version for all packages in parallel (note the double quotes):
0 commit comments