Reorganize contributor docs

.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)

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 Documentation](./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 → 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.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 → docs/code-guidelines/package-guidelines.md

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