Reorganize contributor docs

mcmire · mcmire · commit 0432905fc869 · 2026-01-08T09:08:44.000-07:00
Most of the contributor docs are kept in one main file, but as time as
gone on we have split out specific topics into their own files. Some
files are not linked from the main file at all. Finally, one of the
files in `docs/` is intended for the `core-backend` repo, not the repo
as a whole.

Ultimately, this is confusing for contributors.

This commit converts the main file to a table of contents, organized by
category, and makes sure to link to every file in `docs/`. It also moves
the `core-backend`-specific file to that package.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -27,5 +27,5 @@ For example:
 
 - [ ] I've updated the test suite for new or updated code as appropriate
 - [ ] I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
-- [ ] I've communicated my changes to consumers by [updating changelogs for packages I've changed](https://github.com/MetaMask/core/tree/main/docs/contributing.md#updating-changelogs)
+- [ ] I've communicated my changes to consumers by [updating changelogs for packages I've changed](https://github.com/MetaMask/core/tree/main/docs/updating-changelogs.md)
 - [ ] I've introduced [breaking changes](https://github.com/MetaMask/core/tree/main/docs/breaking-changes.md) in this PR and have prepared draft pull requests for clients and consumer packages to resolve them
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,32 @@
+# Contributor Guide
+
+Hi! Welcome to the contributor documentation for the `core` monorepo.
+
+## Getting started
+
+- [Setting up your development environment](./getting-started/setting-up-your-environment.md)
+- [Codeownership](./getting-started/codeownership.md)
+- [Code guidelines for this repo](#code-guidelines)
+
+## Processes
+
+- [Performing operations across the monorepo](./processes/general-monorepo-operations.md)
+- [Writing and running tests](./processes/testing.md)
+- [Linting and formatting](./processes/linting-and-formatting.md)
+- [Updating changelogs](./processes/updating-changelogs.md)
+- [Creating pull requests](./processes/creating-pull-requests.md)
+- [Releasing changes](./processes/releasing.md)
+  - [Preparing and releasing breaking changes](./processes/breaking-changes.md)
+  - [Reviewing release PRs](./processes/reviewing-release-prs.md)
+- [Testing changes to packages in other projects](./processes/testing-changes-in-other-projects.md)
+- [Building packages](./processes/building.md)
+- [Adding new packages to the monorepo](./processes/adding-new-packages.md)
+- [Migrating external packages to the monorepo](./processes/package-migration-process-guide.md)
+  - [Migrating tags](./processes/migrate-tags.md)
+
+## Code guidelines
+
+- [General MetaMask code guidelines](https://github.com/MetaMask/contributor-docs)
+- [General guidelines for all packages](./code-guidelines/package-guidelines.md)
+- [Writing controllers](./code-guidelines/controller-guidelines.md)
+- [Writing data services](./code-guidelines/data-services.md)
diff --git a/docs/code-guidelines/controller-guidelines.md b/docs/code-guidelines/controller-guidelines.md
@@ -1,4 +1,4 @@
-# Guidelines for Writing Controllers
+# Guidelines for writing controllers
 
 ## Understand the purpose of the controller pattern
 
diff --git a/docs/code-guidelines/data-services.md b/docs/code-guidelines/data-services.md
@@ -1,4 +1,4 @@
-# Data Services
+# Data services
 
 ## What is a data service?
 
diff --git a/docs/code-guidelines/package-guidelines.md b/docs/code-guidelines/package-guidelines.md
@@ -1,4 +1,4 @@
-# Guidelines for Packages
+# Guidelines for packages
 
 ## List exports explicitly
 
diff --git a/docs/contributing.md b/docs/contributing.md
diff --git a/docs/getting-started/codeownership.md b/docs/getting-started/codeownership.md
@@ -0,0 +1,5 @@
+# Understanding codeowners
+
+Although maintenance of this repository is superintended by the Wallet Framework team, the responsibility of maintenance is expected to be shared among multiple teams at MetaMask. In fact, some teams have codeownership over specific packages. The exact allocation is governed by the [`CODEOWNERS`](../.github/CODEOWNERS) file.
+
+**If your team is listed as a codeowner for a package, you may change, approve pull requests, and create releases without consulting the Wallet Framework team.** Alternatively, if you feel that your team should be granted codeownership over a specific package, you can submit a pull request to change `CODEOWNERS`.
diff --git a/docs/getting-started/setting-up-your-environment.md b/docs/getting-started/setting-up-your-environment.md
@@ -0,0 +1,8 @@
+# Setting up your development environment
+
+1. Install the current LTS version of [Node](https://nodejs.org).
+   - If you are using [NVM](https://github.com/creationix/nvm#installation) (recommended), running `nvm install` will install the latest version, and running `nvm use` will automatically choose the right Node version for you.
+2. Run `corepack enable` to install [Yarn](https://yarnpkg.com) via [Corepack](https://github.com/nodejs/corepack?tab=readme-ov-file#how-to-install).
+   - If you have Yarn installed globally via Homebrew or NPM, you'll need to uninstall it before running this command.
+3. Run `yarn install` to install dependencies and run any required post-install scripts.
+4. 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.
diff --git a/docs/processes/adding-new-packages.md b/docs/processes/adding-new-packages.md
@@ -0,0 +1,29 @@
+# Adding new Packages to the monorepo
+
+> [!NOTE]
+> If you're migrating an existing package to the monorepo, please see [the package migration documentation](./package-migration-process-guide.md). You may be able to make use of `create-package` when migrating your package, but there's a lot more to it.
+
+Manually creating a new monorepo package can be a tedious, even frustrating process. To alleviate that problem, we have created a CLI that automates most of the job for us, creatively titled [`create-package`](../scripts/create-package/). To create a new monorepo package, follow these steps:
+
+1. Create a new package using `yarn create-package`.
+   - Use the `--help` flag for usage information.
+   - Once this is done, you can find a package with your chosen name in `/packages`.
+2. Make sure your license is correct.
+   - By default, `create-package` gives your package an MIT license.
+   - If your desired license is _not_ MIT, then you must update your `LICENSE` file and the `license` field of `package.json`.
+3. Update `.github/CODEOWNERS` and `teams.json` to assign a team as the owner of the new package.
+4. Add your dependencies.
+   - Do this as normal using `yarn`.
+   - Remember, if you are adding other monorepo packages as dependents, don't forget to add them to the `references` array in your package's `tsconfig.json` and `tsconfig.build.json`.
+
+And that's it!
+
+### Contributing to `create-package`
+
+Along with this documentation, `create-package` is intended to be the source of truth for the process of adding new packages to the monorepo. Consequently, to change that process, you will want to change `create-package`.
+
+The `create-package` directory contains a [template package](../scripts/create-package/package-template/). The CLI is not aware of the contents of the template, only that its files have [placeholder values](../scripts/create-package/constants.ts). When a new package is created, the template files are read from disk, the placeholder values are replaced with real ones, and the updated files are added to a new directory in `/packages`. To modify the template package:
+
+- If you need to add or modify any files or folders, just go ahead and make your changes in [`/scripts/create-package/package-template`](../scripts/create-package/package-template/). The CLI will read whatever's in that directory and write it to disk.
+- If you need to add or modify any placeholders, make sure that your desired values are added to both the relevant file(s) and [`/scripts/create-package/constants.ts`](../scripts/create-package/constants.ts). Then, update the implementation of the CLI accordingly.
+- As with placeholders, updating the monorepo files that the CLI interacts with begins by updating [`/scripts/create-package/constants.ts`](../scripts/create-package/constants.ts).
diff --git a/docs/processes/breaking-changes.md b/docs/processes/breaking-changes.md
@@ -1,4 +1,4 @@
-# Preparing & Releasing Breaking Changes
+# Preparing and releasing breaking changes
 
 When developing packages, it is always important to be intentional about the impact that changes have on projects which use those packages. However, special consideration must be given to breaking changes.
 
@@ -73,7 +73,7 @@ For dependent packages located in `core`, you may get type errors immediately th
 
 For other projects that live outside of `core`, you can use the following process to verify the effects:
 
-1. Create a [preview build](./contributing.md#testing-changes-to-packages-with-preview-builds) for your package.
+1. Create a [preview build](./testing-changes-in-other-projects.md#testing-changes-to-packages-with-preview-builds) for your package.
 2. Open draft PRs in the dependent projects.
 3. In each draft PR, upgrade your package to the preview build.
 4. Test the project, particularly the functionality that makes use of your package.
diff --git a/docs/processes/building.md b/docs/processes/building.md
@@ -0,0 +1,8 @@
+# Building packages
+
+[`ts-bridge`](https://github.com/ts-bridge/ts-bridge) is used to build packages in both CommonJS- and ESM-compatible formats.
+
+Built files show up in the `dist/` directory in each package. These are the files which will ultimately be published to NPM.
+
+- Run `yarn build` to build all packages in the monorepo.
+- Run `yarn workspace <workspaceName> run build` to build a single package.
diff --git a/docs/processes/creating-pull-requests.md b/docs/processes/creating-pull-requests.md
@@ -0,0 +1,8 @@
+# Creating pull requests
+
+When submitting a pull request for this repo, take some a bit of extra time to fill out its description. Use the provided template as a guide, paying particular attention to the **Explanation** section. This section is intended for you to explain the purpose and scope of your changes and share knowledge that other engineers might not be able to see from reading the PR alone. Some questions you should seek to answer are:
+
+- What is the motivator for these changes? What need are the changes satisfying? Is there a ticket you can share or can you provide some more context for people who might not be familiar with the domain?
+- Are there any changes in particular whose purpose might not be obvious or whose implementation might be difficult to decipher? How do they work?
+- If your primary goal was to update one package but you found you had to update another one along the way, why did you do so?
+- If you had to upgrade a dependency, why did you do so?
diff --git a/docs/processes/general-monorepo-operations.md b/docs/processes/general-monorepo-operations.md
@@ -0,0 +1,11 @@
+# Performing operations across the monorepo
+
+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:
+
+- [`yarn workspace`](https://yarnpkg.com/cli/workspace)
+- [`yarn workspaces foreach`](https://yarnpkg.com/cli/workspaces/foreach)
+
+> **Note**
+>
+> - `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`.
+> - `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'`.
diff --git a/docs/processes/linting-and-formatting.md b/docs/processes/linting-and-formatting.md
@@ -0,0 +1,8 @@
+# Linting and formatting code
+
+[ESLint](https://eslint.org) v9 (via [MetaMask's shared ESLint configurations](https://github.com/MetaMask/eslint-config)) is used to check for code quality issues, and [Prettier](https://prettier.io/docs/en/) is used to format files.
+
+If you need to customize the behavior of ESLint, see `eslint.config.mjs` in the root.
+
+- Run `yarn lint` to lint all files and show possible violations across the monorepo.
+- Run `yarn lint:fix` to fix any automatically fixable violations.
diff --git a/docs/processes/migrate-tags.md b/docs/processes/migrate-tags.md
@@ -1,6 +1,6 @@
-# `migrate-tags`
+# Migrating tags from other repos
 
-When migrating libraries into the core monorepo, the original git history is transferred using the `git-filter-repo` tool (instructions [here](https://github.com/MetaMask/core/issues/1079#issuecomment-1700126302)), but tags attached to release commits are excluded from the process. This is because the tag names (`v[major].[minor].[patch]`) first need to be adjusted to conform to the scheme used by the core repo (`@metamask/<package-name>@[major].[minor].[patch]`).
+When migrating libraries into the core monorepo, the original git history is transferred using the `git-filter-repo` tool (instructions [here](./package-migration-process-guide.md)), but tags attached to release commits are excluded from the process. This is because the tag names (`v[major].[minor].[patch]`) first need to be adjusted to conform to the scheme used by the core repo (`@metamask/<package-name>@[major].[minor].[patch]`).
 
 The `./scripts/migrate-tags.sh` script automates the process of enumerating the tags and associated release commit messages in the original repo, searching the migrated git history in the core repo's `merged-packages/<package-name>` directory for each commit message, creating tags with correctly-formatted names and attaching them to the found release commits, and pushing those tags to the core repo.
 
diff --git a/docs/processes/package-migration-process-guide.md b/docs/processes/package-migration-process-guide.md
@@ -1,4 +1,4 @@
-# Package Migration Process Guide
+# Package migration process guide
 
 This document outlines the process for migrating a MetaMask library into the core monorepo. The migration target is assumed to comply with the requirements defined by [`metamask-module-template`](https://github.com/MetaMask/metamask-module-template) and [`module-lint`](https://github.com/MetaMask/module-lint).
 
diff --git a/docs/processes/releasing.md b/docs/processes/releasing.md
diff --git a/docs/processes/reviewing-release-prs.md b/docs/processes/reviewing-release-prs.md
diff --git a/docs/processes/testing-changes-in-other-projects.md b/docs/processes/testing-changes-in-other-projects.md
diff --git a/docs/processes/testing.md b/docs/processes/testing.md
diff --git a/docs/processes/updating-changelogs.md b/docs/processes/updating-changelogs.md
diff --git a/docs/real-time-balance-updates-flow.md b/docs/real-time-balance-updates-flow.md

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Guidelines for Writing Controllers`
	`1`	`+# Guidelines for writing controllers`
`2`	`2`
`3`	`3`	`## Understand the purpose of the controller pattern`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Data Services`
	`1`	`+# Data services`
`2`	`2`
`3`	`3`	`## What is a data service?`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Guidelines for Packages`
	`1`	`+# Guidelines for packages`
`2`	`2`
`3`	`3`	`## List exports explicitly`
`4`	`4`