Requests for comment/Migrate code review and management to Phabricator from Gerrit

Tracked in Phabricator
Task T119908

Request for comment (RFC)

Migrate code review and management to Phabricator from Gerrit
Component	General
Creation date	30 November 2015
Author(s)	Chad Horohoe, Mukunda Modell, Greg Grossmeier
Document status	declined See Phabricator.

This is an RFC to migrate code-review from Gerrit to Phabricator's Differential.

Background

We have used Gerrit for code review since the migration from Subversion to Git, circa early 2012. In 2015, we migrated from Bugzilla to Phabricator for our bug tracking. Phabricator also includes code management and review tools, and in fact these tools were a large part of the reason we chose Phabricator for our development platform.

Problem

Gerrit has a very high learning curve for new developers (cf: task T114419), is difficult to maintain and does not integrate well with Phabricator. Continued maintenance of Gerrit has a very high cost and is yet another software tool to maintain by a small team.

Process

See also:

• The WMF Release Engineering Team's Differential Migration goal project page for context and a rough (quarterly, iow: 3 month chunks) timeline.
• The #Gerrit-Migration project in Phabricator which holds all tasks blocking the migration

Some milestones along the way

(not all in a strict dependency order)

1. Deprecate Gitblit (ie: git.wikimedia.org) and host all repositories in Phabricator ("Diffusion")
   • Tracked via #gitblit-deprecate -  Done
2. Import all repos from Gerrit - task T616 -  Done
3. Get early adopters using Differential for "small" self-contained projects - task T129301
   • Doing this will give us real-world examples of code-review in Phabricator
4. Prototype CI with Differential - task T103127 -  Done
5. Integrate CI with Differential - task T31
6. Broadcast Differential activity to IRC - task T116330
7. Document code review workflows - task T117058
8. Update Code Review related wiki pages - task T207
9. Have Phabricator take over Github replication - task T115624
10. Stop taking in new projects to Gerrit
11. Migrate open changes from Gerrit to Differential - task T122979
12. Provide static dump of Gerrit - task T617
13. SWITCH OVER (things after this are not absolute blockers/needed before switch over)
14. Make MetricsGrimoire/korma support gathering Code Review statistics from Phabricator's Differential - task T118753

Pros and Cons of migrating to Phabricator/Differential

see also the original Phabricator RFC

Pros

• Everything would be in one place
  • This benefit can not be understated
  • Single login for everything (it uses your Wikimedia SUL account)
  • Built in integration of subsystems like bug tracker, code-review, etc
  • Single interface across subsystems (reduced cognitive load/confusion)
  • Integrates design and designers (via Pholio)
  • Conversations allowed to stay in one place (instead of spread across multiple platforms)
  • Reduce technical-debt maintained by our community by no longer maintaining a family of home-grown integration bots (see: [| grrrit-wm] and potentially wikibugs2) and instead use/extend the Phabricator Bot.
• Reducing the technical debt maintained by the WMF by:
  • Decommissioning Gitblit
  • Decommissioning Gerrit
• Mobile-friendly
  • Login from any mobile device and see what you can read and do. Now, open Bugzilla or Gerrit...
• Support for code auditing, with automatic notification based on herald rules and conditions
  • Audit cowboy commits triggered automatically and appropriate teams can be notified.
  • Raise concern about a commit that is already past code review.
  • Similar UI to differential but simplified and with different states for a commit:
    • "Needs audit" for commits that bypassed code review
    • "Concern raised" for manually flagged commits
    • Must be accept by someone with "ownership" of the code in question.
• Faster and much more enjoyable code review experience (especially large diffs), and improved commit/review procedures
  • arc patch D123 vs git review -d 239028
  • differential comments are actually readable. vs gerrit is completely illegible, and if that weren't bad enough, no amount of css can fix it because the markup is pathological. Gerrit code review: Intentionally 99% css-resistant in the 21st century.
  • Multi-commit single-branch review support instead of the approach in Gerrit where each change is a single commit that is amended for each new patch set
    • But phabricator supports the single amended commit workflow for those that prefer it.
  • Better visibility of requested reviews - patches awaiting review are easier to notice thanks to dashboards, an outstanding review counter on the phabricator main menu, and phabricator notifications.
• Possibility to let users create their own repositories
• ease of creating feature branches?
• Wide adoption among our peers.
  • Phabricator is used by prominent open-source projects and and non-profit, free-knowledge organizations such as:
    • Blender
    • FreeBSD
    • Haskell
    • KDE
    • Khan Academy
    • LLVM
  • These and other phabricaor users have created numerous utilities, integrations, workflows and other resources which add a lot of value to the phabricator ecosystem. Many of these resources are documented on Phabricator's wiki: Community Resources
• We have a good working relationship with the upstream project and Phacility have gone out of their way, on multiple occasions, to accommodate Wikimedia's needs and workflows.

Cons

• Code review workflow differs of the Gerrit workflow when several persons want to improve a single commit: Gerrit allows to smoothly add a new revision, with author still being the initial proponent. Differential requires you commandeer the revision: you become author, and so you can't approve it as you can't self review (side effect: we so need to enable self review in the config, even if we don't socially use it). It "steals" the revision from the author, which becomes a review subscriber, and the revision is now officially yours. In pratice, this means people won't do that and will block a review for an extraneous space instead of fix it quickly, approve it, and send it to Zuul for merge.
• Arcanist required
  • not for much longer
  • Arcanist is easy to install on every platform, ArchLinux excepted, and is also available as a Docker container
• Transition learning curve (inherent to any migration)
  • Can be partly addressed via trainings and documentation (which mostly already exists, e.g. Phabricator/Differential)
• Single Point of Failure
  • isn't gerrit a single point of failure now?
  • Phabricator supports repo mirroring and high availability clustering
  • Can be mitigated
• Repository callsigns. This is being addressed with task T110607
• Rewrite a bunch of bots relating to Gerrit
  • Gerritbot is no more needed (Phabricator has a built-in IRC notifier)
    • The notifier code has been broken since May 2015. Yet, something custom could be built around Doorkeeper.
  • wikibugs needs to be updated, maybe? (see pros)
• Impact on CI, needs the middleware glue to Jenkins/Nodepool

Alternatives

What, if any, alternatives are there to moving to Phabricator/Differential?

Status quo: Gerrit

We could stick with Gerrit, but the general consensus has always been with Gerrit that the learning curve is very steep. It's a terrible maintenance burden.

Other tools

Basically, the existing code review tools that aren't Phabricator can boil down to a couple of groups:

Outside hosted / closed source (Github, Gitlab, Cruicable, etc)

Generally involve close-sourced platforms. We cannot deploy from an outside service, so we would still require mirroring back to Phabricator or elsewhere internally for deployments. Gitlab does have a self-hosted option that is free, but is a scaled back version of their "Enterprise" version, which has closed source components we would need. Generally use a Pull Request model which is familiar to most people.

Gerrit-esque tools (Reitveld, Reviewboard, etc)

Basically everything else worth using that is free software is in the "Gerrit" sphere. Either they're directly related (eg: Reitveld), or they go out of their way to make their UI and workflows Gerrit-esque. See the status quo.

There's also a ton of weird one-off tools that are half-developed, abandoned, incredibly workflow-specific or technically unsuitable (platform requirements, etc).

Investigate

• Replication to GitHub
  • Yes, it does support it. Working on small scale already.
• access lists inheritance (eg: operations/* analytics/* mediawiki/* ..)
  • this would use the acl*projects in phabricator
• review dashboards
  • https://phabricator.wikimedia.org/differential/query/active/ for the default
• search queries (ex: all changes I am a reviewer on and which I haven't voted CR yet: is:open reviewer:self label:code-review=0,self ie: https://gerrit.wikimedia.org/r/#/q/is:open+reviewer:self+label:code-review%253D0%252Cself,n,z )
  • https://phabricator.wikimedia.org/differential/query/advanced/
  • Set "reviewers" to you, and status "needs review"
  • see also "blocking reviewers" vs "reviewers" in Differential
• dependencies between changes across repos
  • Differential allows you to indicate any other Diff as a dependency of any given Diff
• private repos / patches
  • Bad feature of Gerrit, will not be re-doing.