diff --git a/docs/content/en/docs/contributing.md b/docs/content/en/docs/contributing.md index d359c77b9..670e53049 100644 --- a/docs/content/en/docs/contributing.md +++ b/docs/content/en/docs/contributing.md @@ -89,39 +89,74 @@ at the [pull request review stage](#pull-request-review-flow). ### Pull request review flow 1. **New PR**: - -- When a new PR is submitted, it is inspected for quality requirements, such as - the CLA requirement, and a sufficient PR description. -- If the PR passes checks, we assign a reviewer. If not, we request additional - changes to ensure the PR passes CI checks. - + - When a new PR is submitted, it is inspected for quality requirements, such as + the CLA requirement, and a sufficient PR description. + - If the PR passes checks, we assign a reviewer. If not, we request additional + changes to ensure the PR passes CI checks. 2. **Review** - -- A reviewer will check the PR and potentially request additional changes. -- If a change is needed, the contributor is requested to make a suggested - change. Please make changes with additional commits to your PR, to ensure that - the reviewer can easily see the diff. -- If all looks good, the reviewer will approve the PR. -- This cycle repeats itself until the PR is approved. - + - A reviewer will check the PR and potentially request additional changes. + - If a change is needed, the contributor is requested to make a suggested + change. Please make changes with additional commits to your PR, to ensure that + the reviewer can easily see the diff. + - If all looks good, the reviewer will approve the PR. + - This cycle repeats itself until the PR is approved. 3. **Approved** - -- **At this stage, you must squash your commits into a single commit.** -- Once the PR is approved, a GitHub workflow will - [check](https://github.com/google/heir/blob/main/.github/workflows/pr_review.yml) - your PR for multiple commits. You may use the `git rebase -i` to squash the - commits. Pull requests must comprise of a single git commit before merging. - + - **At this stage, you must squash your commits into a single commit.** + - Once the PR is approved, a GitHub workflow will + [check](https://github.com/google/heir/blob/main/.github/workflows/pr_review.yml) + your PR for multiple commits. You may use the `git rebase -i` to squash the + commits. Pull requests must comprise of a single git commit before merging. 4. **Pull Ready** - -- Once the PR is squashed into a single git commit, a maintainer will apply the - `pull ready` label. -- This initiates the internal code migration and presubmits. -- If needed, we may come to you to make some minor changes in case tests fail at - this stage. If so, we will request changes from the GitHub UI and the PR must - be approved again. -- At times, it may not be your change, but it may be additional internal lints - and layering checks that are not integrated with `bazel` or open-source - tooling. We will go ahead and fix this. -- Once the internal tests pass, we merge the code internally and externally. You - will see `copybara-bot` close the PR and merge your commit directly into main. + - Once the PR is squashed into a single git commit, a maintainer will apply the + `pull ready` label. + - This initiates the internal code migration and presubmits. + - After the internal process is finished, the commit will be added to `main` + and the PR closed as merged by that commit. + +### Internal review details + +This diagram summarizes the GitHub/Google code synchronization process. This +is largely automated by a Google-owned system called Copybara, the configuration +for which is Google-internal only. This system treats the Google-internal +version of HEIR as the source of truth, and applies specified transformation +rules to copy internal changes to GitHub and integrate external PRs internally. + +Notable aspects: + +- The final merged code may differ slightly from a PR. The changes are mainly + to support stricter internal requirements for BUILD files that we cannot + reproduce externally due to minor differences between Google's internal build + systems and bazel that we don't know how to align. Sometimes they will also + include additional code quality fixes suggested by internal static analyzers + that do not exist outside of Google. +- Due to the above, signed commits with internal modifications will not + maintain valid signatures after merging, which labels the commit with a + warning. +- You will see various actions taken on GitHub that include `copybara` in the + name, such as changes that originate from Google engineers doing various + approved migrations (e.g., migrating HEIR to support changes in MLIR or + abseil). + +{{< figure title="A diagram summarizing the copybara flow for HEIR internally to Google" src="/images/hugo-copybara.png" link="/images/hugo-copybara.png" >}} + +### Why bother with Copybara? + +tl;dr: Automatic syncing with upstream MLIR and associated code migration. + +Until HEIR has a formal governance structure in place, Google +engineers—specifically Asra Ali, Shruthi Gorantala, and Jeremy Kun—are the +codebase stewards. Because the project is young and the team is small, we want +to reduce our workload. One important aspect of that is keeping up to date +with the upstream MLIR project and incorporating bug fixes and new features +into HEIR. Google also wishes to stay up to date with MLIR and LLVM, and so +it has tooling devoted to integrating new MLIR changes into Google's monorepo +every few hours. As part of that rotation, a set of approved internal projects +that depend on MLIR (like TensorFlow) are patched to support breaking changes +in MLIR. HEIR is one of those approved projects. + +As shown in the previous section, the cost of this is that no change can go +into HEIR without at least two Googlers approving it, and the project is held +to a specific set of code quality standards, namely Google's. We acknowledge +these quirks, and look forward to the day when HEIR is useful enough and +important enough that we can revisit this governance structure with the +community. diff --git a/docs/static/images/heir-copybara.png b/docs/static/images/heir-copybara.png new file mode 100644 index 000000000..4de739c7a Binary files /dev/null and b/docs/static/images/heir-copybara.png differ