Skip to main content

Github Management

Status: Complete

Background​

As members of the XMTP Labs team, we have a need to coordinate and communicate around the work that we're doing day-to-day. Likewise, there is documentation that we rely on that's applicable to our individual teams, but also has the potential to be applicable to the team more broadly.

Github is an open-ended solution with many possibilities on how to communicate and coordinate around work and documentation and we need to pick a path.

Problem​

As we begin to work within Github exclusively as our task/product/project management solution, we must decide to go with multirepos for team and/or project or a monorepo.

Use cases​

  • Use Github Issues for general task, product, and project management with XMTP
    • Issue management has the potential of being more challenging for cross-functional work
      • Or requiring that people must visit many repos to understand all of their work
  • Use a team folders as a destination for durable documentation and record of decision-making
  • Keeping a handbook for the entire team in one repo
    • Have a /handbook/ folder in each team's folder, as well as a general /handbook/ directory for non-team documentation, with a shared index README that acts as a unified directory for all teams

Goals​

  • Provide a source of truth for the team
    • For high-level project planning, a shared handbook, and likely non-engineering-related issues
  • Have a reliable place for cross-functional work to get done
  • Enable "ambient awareness" among the team
    • Writing things into a monorepo simplifies discovery of things being done amongst the whole team
  • Enable institutional knowledge within the team
    • By capturing as much into Github as makes sense, we preserve a history of our decisionmaking and current state for benefit of the whole team'
      • It's especially relelvant for new team members

Non-goals​

  • Accounting for issues/pull requests in repositories that require outside contribution
    • These will need to continue being in their own repository
  • Requiring all issues & PRs to go into this monorepo
    • It's likely that most of engineering-related work will be done in other repos, and therefore expected related issues and PRs will remain with those repos.

Solution​

  • Use a monorepo for team documentation and work coordination
  • Set up a robust CODEOWNERS file to ensure that the review process is streamlined and reduces noise

Plan​

Questions​

  • How do keep the notification noise down and ensure notifications which don't bear relevance to a team member will be kept to a minimum?
  • How can we configure CODEOWNERS to most effectively manage the monorepo?
  • What negatives about code monorepos persist in monorepos more focused around documentation?