KPIs

• Less than x10 the number of core team developers open (at this moment 5x10=50)
• No PRs without a label.

Labels

• You can find the list of the available labels under GitHub labels. We replicate them between all the repositories.
• The label must have a description if needed to clear the confusion.
• A pull request or issue might have primary labels prefixed to the title. This is explained in more detail in the following section.

PR title

• The title might have up to three primary labels. These are prefixed to the title in brackets: [primary-label] Title. For instance, the primary label of this issue is [Tooltip]

  

• The primary labels must match with an existing GitHub label, keeping the same format. For instance, use [docs] and not [Docs], as the GitHub label is lowercase docs: docs.

• The primary labels must have the following order depending on their category: [*Cross-package* or *package*][*platform*][*artifact*], the categories being:

  • Cross-package: core, scope: docs-infra, or scope: code-infra
  • Package: The related package label package: xxx
  • Platform: docs, blog, or website (When the platform is code, it’s omitted)
  • Artifact: ****The related component or function, e.g., component: YyyY

  If there’s more than one label per category (e.g., base-ui and material-ui), then both should be added in alphabetical order (e.g., [base-ui][material-ui]).

• We might not always create all the GitHub labels. For instance, with artifacts, it can be overwhelming. We allow the use of React component names when relevant:

  1. If it's about a specific React component or function, you can use the JS export name e.g., [TreeItem] Fix missing type context
  2. If it's broader than one specific React component, use the component name (not the React component name) e.g., [tree view] Add virtualization as the GitHub label is component: tree view.

• Please use the same guidelines for writing a pull request title as you would use for the git commit messages https://chris.beams.io/posts/git-commit/. Mainly, the title should stay short, use the imperative mood, have primary labels and description

PR description

• If the changes are trivial, like a 1 line change typo fix, the description can be omitted.
• If the issue is meant to solve a specific GitHub issue, always link it with Fix #1234.
• If the issue is related to a specific GitHub issue, for example, it's one step toward solving it, always like it with Related to #1234.
• Any developers (e.g., customers) must be able to understand from the description the following:
  • What problem are we solving? e.g., it can be detailed or come from a link to the GitHub issue
  • What are the key design decisions? For instance, what are the alternative options, and why do we ignore them?
• This is important for future scrutiny, peer reviews, clarity of thinking, and users’ trust.

PR reviews

• Comments left in a pull request's review can be approved in two different circumstances:

  • If the comment touches on a complex aspect dimension, only the author of the comment can resolve it.
  • If the comment suggests a straightforward solution anyone can resolve it once it seems fixed.

• Comments left in a pull request that is off-topic to the problem fixed should be prefixed with Off-topic. These comments don't need to be resolved to merge.

  If the discussion can't easily be resolved a follow-up GitHub issue and pull request must be opened. It allows the initial pull request to be merged, regardless.

Merging PRs

• We empty the default description field to keep the git history clean before merging PRs. For PRs that have 50+ commits, having each commit message concatenated makes it hard to read the history, either using git log:

  

  or a GUI like gitk. Plus the commit information has usually no value.