About Gerrit Code Review

Gerrit code review for large, distributed projects.

(The Discord server said this was too long. Also, it might be worth referring to later.)

Branching and merging works for small teams and mono repos. It gets messy when you have big projects.
Enter “change lists”.
Rather than reconcile changes to a branch, Gerrit code review(aka git-review in PyPi) groups commits into a “change list” and manages those changes independently.
This makes it easier to keep a single main working branch. The way the opendev.org team describes it:

The difference is subtle, but significant. In the pull request model, you create a fork of the original repository, push changes to it, and ultimately propose to merge changes back. In the change proposal model, you prepare a change, and propose it. You do not create a complete fork and everyone contributes into the same original repository with what are basically lightweight, ephemeral topic branches. It results in less fragmentation overall, and avoids confusion between the original repository and its numerous forks.

That high-level difference also affects lower-level details. A pull request may contain several commits, and if merged all those commits will appear in the original repository history. In Gerrit, every commit is a separate change (optionally depending on other related changes) for code reviewers to review, so developers squash or amend edits made while developing to represent the desired final state of that change. Each prior revision of a change is still retained by the service, as are all the review comments, so updates can be compared side-by-side for a clear picture of how the change evolved. It generally results in easier code review, but also a cleaner branch history with the commit messages reviewed as an integral part of each change.

In summary, the Gerrit workflow, its user experience and UI are different from the pull request workflow. While it may not be immediately familiar to developers used to pull request workflows, it’s worth learning. Long-term benefits outweigh the short-term cost of having to learn a new tool, especially for someone who is going to spend a lot of time developing for that project anyway.