| = Gerrit Code Review - A Quick Introduction |
| |
| Gerrit is a web-based code review tool built on top of the |
| https://git-scm.com/[git version control system]. This introduction provides |
| an overview of Gerrit and describes how Gerrit integrates into a typical |
| development workflow. It also provides a brief tutorial that shows how to manage |
| a change using Gerrit. |
| |
| == What is Gerrit? |
| |
| Gerrit makes code review easy by providing a lightweight framework for reviewing |
| commits before they are accepted by the codebase. Gerrit works equally well for |
| projects where approving changes is restricted to selected users, as is typical |
| for Open Source software development, as well as projects where all contributors |
| are trusted. |
| |
| == Gerrit and the developer workflow |
| |
| To understand how Gerrit fits into and enhances the developer workflow, consider |
| a typical project. This project has a central source repository, which serves as |
| the authoritative copy of the project's contents. |
| |
| .Central Source Repository |
| image::images/intro-quick-central-repo.png[Authoritative Source Repository] |
| |
| Gerrit takes the place of this central repository and adds an additional |
| concept: a _store of pending changes_. |
| |
| .Gerrit in place of Central Repository |
| image::images/intro-quick-central-gerrit.png[Gerrit in place of Central Repository] |
| |
| With Gerrit, when a developer makes a change, it is sent to this store of |
| pending changes, where other developers can review, discuss and approve the |
| change. After enough reviewers grant their approval, the change becomes an |
| official part of the codebase. |
| |
| In addition to this store of pending changes, Gerrit captures notes |
| and comments about each change. These features allow developers to review |
| changes at their convenience, or when conversations about a change can't |
| happen face to face. They also help to create a record of the conversation |
| around a given change, which can provide a history of when a change was made and |
| why. |
| |
| Like any repository hosting solution, Gerrit has a powerful |
| link:access-control.html[access control model.] This model allows you to |
| fine-tune access to your repository. |
| |
| == Working with Gerrit: An example |
| |
| To understand how Gerrit works, let's follow a change through its entire |
| life cycle. This example uses a Gerrit server configured as follows: |
| |
| * *Hostname*: gerrithost |
| * *HTTP interface port*: 8080 |
| * *SSH interface port*: 29418 |
| |
| In this walkthrough, we'll follow two developers, Max and Hannah, as they make |
| and review a change to a +RecipeBook+ project. We'll follow the change through |
| these stages: |
| |
| . Making the change. |
| . Creating the review. |
| . Reviewing the change. |
| . Reworking the change. |
| . Verifying the change. |
| . Submitting the change. |
| |
| NOTE: The project and commands used in this section are for demonstration |
| purposes only. |
| |
| === Making the Change |
| |
| Our first developer, Max, has decided to make a change to the +RecipeBook+ |
| project he works on. His first step is to get the source code that he wants to |
| modify. To get this code, he runs the following `git clone` command: |
| |
| ---- |
| $ git clone ssh://gerrithost:29418/RecipeBook.git RecipeBook |
| Cloning into RecipeBook... |
| ---- |
| |
| After he clones the repository, he makes a change to the file and commits it |
| locally. |
| |
| NOTE: At this point, the workflow is exactly the same as it would be if Max was |
| not using Gerrit. |
| |
| Max is ready to create a commit message for his change. When he does, he |
| includes a link:user-changeid.html[Change-Id]. This ID allows Gerrit to link |
| together different versions of the same change being reviewed. |
| |
| === Creating the Review |
| |
| Max's next step is to push his change to Gerrit so other contributors can review |
| it. He does this using the `git push origin HEAD:refs/for/master` command, as |
| follows: |
| |
| ---- |
| $ <work> |
| $ git commit |
| [master 9651f22] Change to a proper, yeast based pizza dough. |
| 1 files changed, 3 insertions(+), 2 deletions(-) |
| $ git push origin HEAD:refs/for/master |
| Counting objects: 5, done. |
| Delta compression using up to 8 threads. |
| Compressing objects: 100% (2/2), done. |
| Writing objects: 100% (3/3), 542 bytes, done. |
| Total 3 (delta 0), reused 0 (delta 0) |
| remote: |
| remote: New Changes: |
| remote: http://gerrithost:8080/68 |
| remote: |
| To ssh://gerrithost:29418/RecipeBook.git |
| * [new branch] HEAD -> refs/for/master |
| ---- |
| |
| The `refs/for/master` branch is a symbolic branch that Gerrit uses to create |
| reviews for the master branch. If Max opted to push to a different branch, he |
| would have modified his command to |
| `git push origin HEAD:refs/for/<branch_name>`. Gerrit automatically creates a |
| `refs/for/<branch_name>` for every branch that it tracks. |
| |
| The output of this command also contains a link to a web page Max can use to |
| review this commit. Clicking on that link takes him to a screen similar to |
| the following. |
| |
| .Gerrit Code Review Screen |
| image::images/intro-quick-new-review.jpg[Gerrit Review Screen] |
| |
| This is the Gerrit code review screen, where other contributors can review |
| his change. Max can also perform tasks such as: |
| |
| * Looking at the link:user-review-ui.html#diff-preferences[diff] of his change |
| * Writing link:user-review-ui.html#inline-comments[inline] or |
| link:user-review-ui.html#reply[summary] comments to explain what he did and |
| why |
| * link:intro-user.html#adding-reviewers[Adding a list of people] that should |
| review the change |
| |
| In this case, Max opts to manually add the senior developer on his team, Hannah, |
| to review his change. |
| |
| === Reviewing the Change |
| |
| Let's now switch to Hannah, the senior developer who will review Max's change. |
| |
| As mentioned previously, Max chose to manually add Hannah as a reviewer. Gerrit |
| offers other ways for reviewers to find changes, including: |
| |
| * Using the link:user-search.html[search] feature that to find changes |
| * Setting up link:user-notify.html[email notifications] to stay informed of |
| changes even if you are not added as a reviewer |
| |
| Because Max added Hannah as a reviewer, she receives an email telling her about |
| his change. She opens up the Gerrit code review screen and selects Max's change. |
| |
| .Gerrit Code Review Screen |
| image::images/intro-quick-new-review.jpg[Gerrit Review Screen] |
| |
| Notice the two "Need" lines: |
| |
| ---- |
| * Need Verified |
| * Need Code-Review |
| ---- |
| |
| These two lines indicate what checks must be completed before the change is |
| accepted. The default Gerrit workflow requires two checks: |
| |
| * *Code-Review*. This check requires that someone look at the code and ensures |
| that it meets project guidelines, styles, and other criteria. |
| * *Verified*. This check means that the code actually compiles, passes any unit |
| tests, and performs as expected. |
| |
| In general, the *Code-Review* check requires an individual to look at the code, |
| while the *Verified* check is done by an automated build server, through a |
| mechanism such as the |
| link:https://wiki.jenkins-ci.org/display/JENKINS/Gerrit+Trigger[Gerrit Trigger |
| Jenkins Plugin]. |
| |
| IMPORTANT: The Code-Review and Verified checks require different permissions |
| in Gerrit. This requirement allows teams to separate these tasks. For example, |
| an automated process can have the rights to verify a change, but not perform a |
| code review. |
| |
| With the code review screen open, Hannah can begin to review Max's change. She |
| can choose one of two ways to review the change: unified or side-by-side. |
| Both views allow her to perform tasks such as add |
| link:user-review-ui.html#inline-comments[inline] or |
| link:user-review-ui.html#reply[summary] comments. |
| |
| Hannah opts to view the change using Gerrit's side-by-side view: |
| |
| .Side By Side Patch View |
| image::images/intro-quick-review-line-comment.jpg[Adding a Comment] |
| |
| Hannah reviews the change and is ready to provide her feedback. She clicks the |
| *Review* button on the change screen. This allows her to vote on the change. |
| |
| .Reviewing the Change |
| image::images/intro-quick-reviewing-the-change.jpg[Reviewing the Change] |
| |
| A code review vote is essentially a numerical score between -2 and 2. The |
| possible options are: |
| |
| * `+2 Looks good to me, approved` |
| * `+1 Looks good to me, but someone else must approve` |
| * `0 No score` |
| * `-1 I would prefer that you didn't submit this` |
| * `-2 Do not submit` |
| |
| By default, a change must have at least one `+2` vote and no `-2` votes before |
| it can be submitted. |
| |
| IMPORTANT: Although votes use numerical values, they do not accumulate. Two |
| `+1` votes do not equate to a `+2`. |
| |
| Hannah notices a possible issue with Max's change, so she selects a `-1` vote. |
| She uses the *Cover Message* text box to provide Max with some additional |
| feedback. When she is satisfied with her review, Hannah clicks the |
| *Published Comments* button. At this point, her vote and cover message become |
| visible to to all users. |
| |
| === Reworking the Change |
| |
| Later in the day, Max decides to check on his change and notices Hannah's |
| feedback. He opens up the source file and incorporates her feedback. Because |
| Max set up the link:user-changeid.html[Change-Id commit-msg hook] |
| before he uploaded the change, all he has to do to upload the re-worked change |
| is push another commit with the same Change-Id in the message. To accomplish |
| this, Max needs only perform the following tasks: |
| |
| * Check out the commit |
| * Amend the commit |
| * Push the commit to Gerrit |
| |
| ---- |
| $ <checkout first commit> |
| $ <rework> |
| $ git commit --amend |
| $ git push origin HEAD:refs/for/master |
| Counting objects: 5, done. |
| Delta compression using up to 8 threads. |
| Compressing objects: 100% (2/2), done. |
| Writing objects: 100% (3/3), 546 bytes, done. |
| Total 3 (delta 0), reused 0 (delta 0) |
| remote: Processing changes: updated: 1, done |
| remote: |
| remote: Updated Changes: |
| remote: http://gerrithost:8080/68 |
| remote: |
| To ssh://gerrithost:29418/RecipeBook.git |
| * [new branch] HEAD -> refs/for/master |
| ---- |
| |
| Notice that the output of this command is slightly different from Max's first |
| commit. This time, the output verifies that the change was updated. |
| |
| Having uploaded the reworked commit, Max can go back to the Gerrit web |
| interface and look at his change. |
| |
| .Reviewing the Rework |
| image::images/intro-quick-review-2-patches.jpg[Reviewing the Rework] |
| |
| Notice that there are now two patch sets associated with this change: the |
| initial submission and the rework. |
| |
| When Hannah next looks at Max's change, she sees that he incorporated her |
| feedback. The change looks good to her, so she changes her vote to a `+2`. |
| |
| === Verifying the Change |
| |
| Hannah's `+2` vote means that Max's change satisfies the *Needs Review* |
| check. It has to pass one more check before it can be accepted: the *Needs |
| Verified* check. |
| |
| The Verified check means that the change was confirmed to work. This type of |
| check typically involves tasks such as checking that the code compiles, unit |
| tests pass, and other actions. You can configure a Verified check to consist |
| of as many or as few tasks as needed. |
| |
| NOTE: Remember that this walkthrough uses Gerrit's default workflow. Projects |
| can add custom checks or even remove the Verified check entirely. |
| |
| Verification is typically an automated process using the |
| link:https://wiki.jenkins-ci.org/display/JENKINS/Gerrit+Trigger[Gerrit Trigger Jenkins Plugin] |
| or a similar mechanism. However, there are still times when a change requires |
| manual verification, or a reviewer needs to check how or if a change works. |
| To accommodate these and other similar circumstances, Gerrit exposes each change |
| as a git branch. The Gerrit UI includes a |
| link:user-review-us.html#download[*download*] link in the Gerrit Code Review |
| Screen to make it easy for reviewers to fetch a branch for a specific change. |
| To manually verify a change, a reviewer must have the |
| link:config-labels.html#label_Verified[Verified] permission. Then, the reviewer |
| can fetch and checkout that branch from Gerrit. Hannah has this permission, so |
| she is authorized to manually verify Max's change. |
| |
| NOTE: The Verifier can be the same person as the code reviewer or a |
| different person entirely. |
| |
| .Verifying the Change |
| image::images/intro-quick-verifying.jpg[Verifying the Change] |
| |
| Unlike the code review check, the verify check is pass/fail. Hannah can provide |
| a score of either `+1` or `-1`. A change must have at least one `+1` and no |
| `-1`. |
| |
| Hannah selects a `+1` for her verified check. Max's change is now ready to be |
| submitted. |
| |
| === Submitting the Change |
| |
| Max is now ready to submit his change. He opens up the change in the Code Review |
| screen and clicks the *Publish and Submit* button. |
| |
| At this point, Max's change is merged into the main part of the repository and |
| becomes an accepted part of the project. |
| |
| == Next Steps |
| |
| This walkthrough provided a quick overview of how a change moves |
| through the default Gerrit workflow. At this point, you can: |
| |
| * Read the link:intro-user.html[Users guide] to get a better sense of how to |
| make changes using Gerrit |
| * Review the link:intro-project-owner.html[Project Owners guide] to learn more |
| about configuring projects in Gerrit, including setting user permissions and |
| configuring verification checks |
| |
| GERRIT |
| ------ |
| Part of link:index.html[Gerrit Code Review] |
| |
| SEARCHBOX |
| --------- |