Create outline for documentation around the core monorepo

[Desi McAdam]

This issue is for creating the outline of what would need to go into the contributor documenation around the the architecture of the core monorepo.

Please use the epic for inspiration on what to include here. Epic 1588

As part of this work please get feedback from team to finalize the outline and then create issues for filling in each of the areas of the outline. Please add the tickets to the epic and ensure they are pointed.

[Elliot Winkler]

Here's what I'm thinking for the outline:

1. Anatomy of the monorepo
   • Provide an ASCII version of the file tree structure, with the packages/ directory collapsed, and a summary for each directory/file
2. Yarn
   • Why do we use Yarn?
   • Yarn "Berry"
   • Checking consistency of package manifests with Yarn constraints
3. TypeScript
   • What happens when you run yarn build
   • What are project references and how do they work?
   • Why is there a tsconfig.json and tsconfig.build.json in the root?
   • Why is there a tsconfig.(build.)json and also a tsconfig.packages.(build.).json?
   • How TypeScript resolves @metamask/* modules
4. Jest
   • What happens when you run yarn test
   • How Jest recognizes TypeScript code
   • How Jest resolves @metamask/* modules and how this differs from TypeScript
   • How code coverage is calculated, how to configure coverage thresholds, and how to exclude files/directories
5. ESLint
   • What happens when you run yarn lint
   • A note on ESLint overrides — why do we have them? When should we not have them?
6. TypeDoc
   • What happens when you run yarn build:docs
   • How TypeDoc is set up
7. How to update the dependency graphs in the README

Note that some of these topics could conceivably be split out in their own sections. We should try not to go into too much detail, but mention enough to where people can understand which context/workflow a particular tool fits into.

[Kanthesha Devaramane]

This looks great. And provides the clear expectation on what needs to be documented to mark it complete.

Few suggestions

1. How about starting with introduction to monorepo

2. And then also adding the goal / how we want this to be evolved
   These two points set's the stage for newbies.

3. Adding a high level architecture diagram, showcasing who uses the monorepo and what's behind the monorepo

4. Do we need to also mention about package migration? and link the documentation/guide

[Kanthesha Devaramane]

• Constraints
  What happens when you run yarn constraints

• auto-changelog
  What happens when you run yarn changelog:validate

[Elliot Winkler]

I agree we should have documentation about constraints. I'm curious whether that should be its own page, though, as I can envision that getting fairly large.