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
{{ message }}
Repository navigation
Create outline for documentation around the core monorepo #55
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.
Provide an ASCII version of the file tree structure, with the packages/ directory collapsed, and a summary for each directory/file
Yarn
Why do we use Yarn?
Yarn "Berry"
Checking consistency of package manifests with Yarn constraints
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
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
ESLint
What happens when you run yarn lint
A note on ESLint overrides — why do we have them? When should we not have them?
TypeDoc
What happens when you run yarn build:docs
How TypeDoc is set up
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.
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.
Activity
mcmire commentedon Oct 25, 2023
Here's what I'm thinking for the outline:
packages/directory collapsed, and a summary for each directory/fileyarn buildtsconfig.jsonandtsconfig.build.jsonin the root?tsconfig.(build.)jsonand also atsconfig.packages.(build.).json?@metamask/*modulesyarn test@metamask/*modules and how this differs from TypeScriptyarn lintyarn build:docsNote 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 commentedon Oct 26, 2023
This looks great. And provides the clear expectation on what needs to be documented to mark it complete.
Few suggestions
How about starting with introduction to monorepo
And then also adding the goal / how we want this to be evolved
These two points set's the stage for newbies.
Adding a high level architecture diagram, showcasing who uses the monorepo and what's behind the monorepo
Do we need to also mention about package migration? and link the documentation/guide
kanthesha commentedon Oct 26, 2023
Constraints
What happens when you run
yarn constraintsauto-changelog
What happens when you run
yarn changelog:validatemcmire commentedon Nov 13, 2023
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.