Skip to content

Create outline for documentation around the core monorepo #55

Open

Description

@desi

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.

Activity

  1. mcmire commented on Oct 25, 2023

    @mcmire
    Contributor

    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.

  2. kanthesha commented on Oct 26, 2023

    @kanthesha

    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

  3. kanthesha commented on Oct 26, 2023

    @kanthesha
    • Constraints
      What happens when you run yarn constraints

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

  4. mcmire commented on Nov 13, 2023

    @mcmire
    Contributor

    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.

  5. removed their assignment
    on Mar 20, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions