The Gerrit Workflow

Perhaps you have heard the Git-oriented review system, Gerrit, but one side-effect of this system is how it encourages creating a good Git commit history. The following is a screen-shot of part of the commit history of a repository at work before using Gerrit:

And here is a screen-shot of the same repository a month later once we started using Gerrit:

While the details of the history don’t matter, the older history is much more complicated. Rolling back a commit, or comparing differences with a complicated commit history is painful.

Sometimes, the pain is removed from the history and transferred to the developer trying to add a new change. ;-)

The Gerrit-oriented work-flow may best be illustrated as a collection of three branches, and a little story.

The newest engineer, Fritz, is assigned TICKET-123 to add a feature. After syncing the master branch with a git pull (she had already cloned the repository from Gerrit), she began this dance:

1. She issued: git checkout -b TICKET-123 to begin her work on her own development branch (in the diagram above, this is labeled, developer-branch).
2. She issued lots of small commits while she worked on the project.
3. The project took longer than she thought, so she issued: git sync to pull from master. While she had to do a merge, she felt it better to merge now than later.
4. She squashed all the little commits into one commit.
5. She created the Gerrit review.
6. She went to the Gerrit Dashboard, and found her change, however, by the time she did, the Jenkins validation system discovered that she had a syntax error in the code. Good thing no one on the team could even pull the change into their code base.
7. She quickly made the fix on her development branch, and committed it using: git commit --amend
8. Re-ran the Gerrit review command, patched her original review.
9. She added the members of her team to the list of reviewers (breathing a sigh of relief since Jenkins had already given the review a +1 validation). Gerrit sent them all email messages, but one of the reviewers noticed that she hadn’t updated the README file, and gave the review a -2 rating.
10. She updated the README file on her development branch, and committed, but using another git commit --amend command.
11. She re-ran the Gerrit review command again, which applied another “patch” to the review.
12. This time, the review is given a +2 by a reviewer, the change was merged to the master branch through the Gerrit interface.

Now, every member of the team, including Fritz, will get this change once they pull from master.

In this case, using Gerrit stopped both a syntactical bug as well as an oversight that would have led to increased technical debt. Gerrit reviews are a good thing, but here is some advice:

• Re-read your comments before posting. While code should be viewed objectively, people write code, and comments can be viewed as a personal attack. Soften the tone by:
  • Phrase your opinion as a question.
  • Use the passive English voice¹.
  • Comment on the code, not the programmer.
• Have a thick skin, and try not to take offense during a review of your recent commit (we’re all on the same team with the same goals, right?) Comments on code is just that … comments on code. Don’t assume it is personal.
• If the code doesn’t make sense, request a comment insertion explaining the code. Doesn’t make sense to you now, it won’t make sense to others next month.
• Not sure if the code change actually addresses the goal of the commit? No problem, you can actually pull the review branch from Gerrit to your workstation and try it out.

In the example above, when Fritz committed and pushed her changes to Gerrit, Gerrit created a review branch. This branch, while temporary, is actually accessible.

Let’s suppose that you are to review Fritz’ commit, and Jenkins stamped a green check on it during the validation phase, you aren’t convinced it does the right thing. Well, you can checkout this review branch and play with it, by clicking on the “Copy” button under the “Download” section.