Reorganize contributor docs

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.

Author: mcmire

.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 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
+- [ ] I've communicated my changes to consumers by [updating changelogs for packages I've changed](https://github.com/MetaMask/core/tree/main/docs/processes/updating-changelogs.md)
+- [ ] I've introduced [breaking changes](https://github.com/MetaMask/core/tree/main/docs/processes/breaking-changes.md) in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

.gitignore

@@ -21,6 +21,7 @@ examples/*/docs
 packages/*/coverage
 packages/*/dist
 packages/*/docs
+!packages/core-backend/docs
 scripts/coverage
 
 # yarn v3 (w/o zero-install)
@@ -34,4 +35,4 @@ scripts/coverage
 !.yarn/versions
 
 # typescript
-packages/*/*.tsbuildinfo
+packages/*/*.tsbuildinfo

README.md

@@ -4,7 +4,7 @@ This monorepo is a collection of packages used across multiple MetaMask clients
 
 ## Contributing
 
-See the [Contributor Guide](./docs/contributing.md) for help on:
+See the [Contributor Docuemntation](./docs) for help on:
 
 - Setting up your development environment
 - Working with the monorepo

docs/README.md

@@ -0,0 +1,32 @@
+# Contributor Documentation
+
+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)

docs/controller-guidelines.md …code-guidelines/controller-guidelines.mddocs/controller-guidelines.md renamed to docs/code-guidelines/controller-guidelines.md docs/controller-guidelines.md renamed to 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
 
@@ -64,7 +64,7 @@ class FooController extends BaseController</* ... */> {
 
 ## Provide a default representation of state
 
-Each controller needs a default representation in order to fully initialize itself when [receiving a partial representation of state](#accept-a-partial-representation-of-state). A default representation of state is also useful when testing interactions with a controller's `*:stateChange` event.
+Each controller needs a default representation in order to fully initialize itself when [receiving a partial representation of state](#accept-an-optional-partial-representation-of-state). A default representation of state is also useful when testing interactions with a controller's `*:stateChange` event.
 
 A function which returns this default representation should be defined and exported. It should be called `getDefault${ControllerName}State`.
 
@@ -637,7 +637,7 @@ export type FooControllerMessenger = Messenger<
 >;
 ```
 
-If, in a test, you need to access all of the actions supported by a messenger, use the [`MessengerActions` utility type](../packages/messenger/src/Messenger.ts):
+If, in a test, you need to access all of the actions supported by a messenger, use the [`MessengerActions` utility type](../../packages/messenger/src/Messenger.ts):
 
 ```typescript
 import type { MessengerActions, MessengerEvents } from '@metamask/messenger';
@@ -716,7 +716,7 @@ export type FooControllerMessenger = Messenger<
 >;
 ```
 
-If, in a test, you need to access all of the events supported by a messenger, use the [`MessengerEvents` utility type](../packages/messenger/src/Messenger.ts):
+If, in a test, you need to access all of the events supported by a messenger, use the [`MessengerEvents` utility type](../../packages/messenger/src/Messenger.ts):
 
 ```typescript
 import type { MessengerActions, MessengerEvents } from '@metamask/messenger';
@@ -1432,7 +1432,7 @@ export const selectActiveAccounts = createSelector(
 
 ## Treat state-mutating methods as actions
 
-Just as each property of state [does not require a getter method to be accessed](#remove-getters-in-favor-of-direct-state-access), each property of state does not require a setter method to be updated, either.
+Just as each property of state [does not require a getter method to be accessed](#expose-derived-state-using-selectors-instead-of-getters), each property of state does not require a setter method to be updated, either.
 
 Methods that change the state of the controller do not need to represent granular, low-level operations such as adding, updating, or deleting a single property from state. Rather, they should be designed to support a higher-level task that the consumer wants to carry out. This is ultimately dictated by the needs of the client UI, and so they should also be given a name that reflects the behavior in the UI.
 

docs/data-services.md docs/code-guidelines/data-services.mddocs/data-services.md renamed to docs/code-guidelines/data-services.md

@@ -1,4 +1,4 @@
-# Data Services
+# Data services
 
 ## What is a data service?
 
@@ -480,4 +480,4 @@ class SendController extends BaseController {
 
 ## Learning more
 
-The [`sample-controllers`](../packages/sample-controllers) package has a full example of the data service pattern. including JSDoc for all types, classes, and methods. Check it out and feel free to copy and paste the code you see to your own project.
+The [`sample-controllers`](../../packages/sample-controllers) package has a full example of the data service pattern. including JSDoc for all types, classes, and methods. Check it out and feel free to copy and paste the code you see to your own project.

docs/package-guidelines.md …cs/code-guidelines/package-guidelines.mddocs/package-guidelines.md renamed to docs/code-guidelines/package-guidelines.md docs/package-guidelines.md renamed to docs/code-guidelines/package-guidelines.md

@@ -1,4 +1,4 @@
-# Guidelines for Packages
+# Guidelines for packages
 
 ## List exports explicitly