🎉 PolyGerrit + Chromium FAQ

What's going on?

Chromium and related projects are migrating to use PolyGerrit for code review instead of Rietveld.

PolyGerrit is a brand new UI for Gerrit built using Polymer. Gerrit is an open-source code review tool built directly on top of Git, so it has an innate understanding of repositories, commits, and branches, unlike Rietveld.

When is it happening?

On Thursday, July 6, Gerrit will become the default for new uploads to chromium/src.git. We plan for the transition of all projects to be complete and for Rietveld to be read-only by the end of Q3 2017.

Many projects, such as Skia, WebRTC, and PDFium, have already fully switched from Rietveld to Gerrit.

Why are we switching?

The Chromium infra team is stretched far too thin as it is and keeping the status quo of having one or no owner for the Rietveld codebase isn’t tenable given its fragility. The bus factor is just too low. That coupled with the duplication of effort across the Gerrit and Rietveld projects, it doesn’t make strategic sense. We would rather focus on more important work that will bring immediate benefit to Chromium developers.

Gerrit is a popular system with hundreds of thousands of users worldwide, a large team for both maintenance and development, and buy-in from many groups across Google and the open-source community. It's a platform we can trust to continue to serve our needs into the future.

How do I dogfood it?

When uploading a CL for the first time, simply pass --gerrit to git cl upload. Every time you upload additional patchsets to that CL, it will automatically go to the same review on Gerrit.

If you wish to switch to Gerrit for all of your reviews in a given repo, so you don't have to pass the flag, simply run git config gerrit.host true while in that repo's checkout.

How will this change my current command-line development workflow?

It won't. git cl already supports a the full Rietveld-style workflow with Gerrit transparently. All of the commands that you're used to should work in the way that you're used to; if they don't, please file bugs.

Gerrit does support some other workflows, such as creating one CL from each commit on your local branch, or creating CLs by directly doing a git push HEAD:refs/for/master. You are welcome to use these workflows if you know what you're doing, but just using git cl should work for everyone.

How do I approve CLs? Can I still “LGTM with nits"?

Instead of typing “LGTM” in a comment, you use the Code-Review label. If you want to provide approval along with a review message, you can hit The “Code-Review +1” button inside the Reply dialog box. If you want to quickly approve a CL that hasn't been approved by someone else already, you can just click the “Code-Review +1” button in the upper right corner of the main screen.

The “Code-Review -1” button is similar to “not LGTM” in Rietveld: it blocks the CL from being submitted, and can only be revoked by you personally replacing it with a neutral or positive score; it can't be overridden by other reviewers.

When you approve a change, that approval will carry forward to future patchsets that the author uploads, just like having sticky LGTMs in Rietveld. So you can “LGTM with nits” to your heart's content.

Why can't I approve this change?

Only committers can set the “Code-Review +1” label. In Rietveld, anyone could say “LGTM” and it would look like the CL had been approved, but the commit queue would reject it with “No LGTM from a valid reviewer” if the approver wasn't a committer. In Gerrit we are able to enforce that one step earlier in the process, so only committers can approve CLs.

If you believe that you should have the ability to +1 CLs but don't, please file a Git-Admin ticket describing the issue.

How do I use the commit queue?

You can set the “Commit-Queue +1” label to begin a dry-run of all trybots run by the CQ, or set “Commit-Queue +2” to start an actual run and commit the CL if the tests pass. You can also click the “Dry run” button in the upper right corner, and if the CL has sufficient approvals, a blue “CQ” button will appear in the upper right corner to all one-click submissions to the commit queue.

If you have started a CQ run (either dry-run or full) and want to cancel it, simply click the X on the right hand side of the Commit-Queue label chip in the metadata side bar.

How do I TBR changes?

Very similarly to as you did on Rietveld. If you want to land a change before the reviewers have a chance to approve it, put the appropriate people (making sure you include any necessary OWNERS) on a TBR= line in the commit message. However, the CL also still has to be approved: so set the “Code-Review +1” label yourself as well. The Commit Queue will recognize the combination of self-approval and owners on the TBR= line and allow the CL to be submitted.

What's this I hear about linked accounts?

If you have both @chromium.org and @google.com email addresses, you may want to think about linking or unlinking your accounts. Both have advantages.

Linked accounts allow you, when authenticating as either account, to have all the rights/privileges of both accounts. For example, if your @google.com account has been granted Push access to a repository, but the local commit that you are trying to push has your @chromium.org address in the author/committer fields (because your .gitconfig file specifies that address), you will still be able to push. In addition, your dashboard of incoming reviews will contain all CLs with either of your accounts assigned as the reviewer. However, due to Google’s security policies, this means that when signing in to the web UI, you must always sign in using your @google.com identity, and go through the two-factor auth flow.

Unlinked accounts are completely separate. If your @google.com account doesn’t have the Forge Author and Forge Committer permissions (most don't), it won’t be able to push commits which were committed/authored by your @chromium.org account, and vice versa. So you need to make sure to always have the correct email address configured in each of your local checkouts. In return, however, you can sign in using your @chromium.org credentials from a wholly untrusted machine (such as a ChromiumOS test lab device).

You can check to see if your accounts are already linked by visiting your Settings/Email Addresses page, and seeing if both of your email addresses are listed. If you would like to link or unlink your accounts, please file a bug. If you do choose to use linked accounts, we encourage you to set your @chromium address as the “primary” address on that settings page.

What happened to all my keyboard shortcuts?

Gerrit supports a wide range of keyboard shortcuts. They are not exactly the same as Rietveld's, but they provide the same functionality. You can see a listing of all keyboard shortcuts available on a given page by hitting the “?” key.

Can I review from my phone?

Yes! PolyGerrit works much better on mobile devices than Rietveld ever has, and we want it to be even better. If you do reviews on your phone, please file bugs and feedback to help us improve the experience even more.

What will happen to Rietveld? Will URLs stop working?

URLs will continue to work. Rietveld will be put in read-only mode to preserve change history and URLs. Potential migration of changes to Gerrit will be considered after the switch. A unified CL search interface is being considered.

What about short URLs? Does crrev still work?

For the sake of not breaking old urls embedded in code, bugs, and email lists, we can't make crrev.com/123456 suddenly start pointing at Gerrit. But we have introduced new short urls: crrev.com/c/454545 will redirect to the external Gerrit host, and crrev.com/i/232323 will redirect to the internal host.

Can I filter Gerrit emails the same way I filter Rietveld ones?

Rietveld made it easy to filter emails by appending +owner, +reviewer, or +cc to your email address depending on your role on the CL. While Gerrit doesn't mangle your email address, it does provide invisible footers just for the purpose of filtering (you can see them by clicking "View Original").

To filter for emails about CLs you uploaded, try includes 'Gerrit-Owner: Your Name'. For changes that you are a reviewer on, try includes 'Gerrit-Reviewer: Your Name' and excludes 'Gerrit-Owner: Your Name'. Finally, for changes that you are CCed on, you want includes 'Gerrit-CC: Your Name'.

What are some known issues I should watch out for / ignore?

There are a lot of small issues that have been reported to us that we hope to get to in the near future. You can see the ones that Chrome Infra is working on here, and the ones that Gerrit Team is working on here.

Gerrit does have both copy and rename detection, but: the thresholds for both are stuck at 60%, and the circumstances under which it detects a copy require that the original also be renamed rather than simply modified in the same commit. Work to loosen these restrictions is ongoing.

Gerrit sends more email than folks are accustomed to from Rietveld. We are working on both reducing the amout of email sent by default and by making our tools which use the Gerrit API (such as the commit queue) operate more silently when they can.

Gerrit sometimes seems slower that Rietveld, especially for small changes. Unfortunately, this latency is the compromise we make for having a highly replicated globally distributed database underlying all of our review data. The Gerrit backend team is constantly working to improve latency (for example, the time to save edits to the commit message has dropped from 30 seconds to less than one), but there is always more work to do.

Where should I file bugs?

If you run into any issues interacting with your CLs from the command line or landing them via the commit queue, please file a bug here. If you run into any issues using the PolyGerrit web application, please file a bug here.

How can I follow progress?

All Chromium-specific bugs related to the migration have been put into milestones:

Additionally, on the Gerrit project, there is a list of Chromium-specific bugs.

What if I have questions not answered here?

Please email infra-dev+polygerrit@chromium.org