290 lines
11 KiB
Plaintext
290 lines
11 KiB
Plaintext
= 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*: 80
|
|
* *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
|
|
----
|
|
|
|
After he clones the repository, he runs a couple of commands to add a
|
|
link:user-changeid.html[Change-Id] to his commits. This ID allows Gerrit to link
|
|
together different versions of the same change being reviewed.
|
|
|
|
....
|
|
scp -p -P 29418 gerrithost:hooks/commit-msg RecipeBook/.git/hooks/
|
|
chmod u+x .git/hooks/commit-msg
|
|
....
|
|
|
|
NOTE: To learn more about adding a change-id and the commit message hook, see
|
|
the link:cmd-hook-commit-msg.html[commit-msg Hook] topic.
|
|
|
|
== 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 3cc9e62] Change to a proper, yeast based pizza dough.
|
|
1 file changed, 10 insertions(+), 5 deletions(-)
|
|
$ git push origin HEAD:refs/for/master
|
|
Counting objects: 3, done.
|
|
Delta compression using up to 8 threads.
|
|
Compressing objects: 100% (2/2), done.
|
|
Writing objects: 100% (3/3), 532 bytes | 0 bytes/s, done.
|
|
Total 3 (delta 0), reused 0 (delta 0)
|
|
remote: Processing changes: new: 1, done
|
|
remote:
|
|
remote: New Changes:
|
|
remote: http://gerrithost/#/c/RecipeBook/+/702 Change to a proper, yeast based pizza dough.
|
|
remote:
|
|
To ssh://gerrithost:29418/RecipeBook
|
|
* [new branch] HEAD -> refs/for/master
|
|
----
|
|
|
|
Notice the reference to a `refs/for/master` branch. Gerrit uses this branch 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 accepts pushes to
|
|
`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.png[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 ask reviewers for advice
|
|
on particular aspects of the change
|
|
* 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
|
|
* Selecting *Open* from the *Changes* menu
|
|
* 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.
|
|
|
|
Notice the *Label status* section above:
|
|
|
|
----
|
|
Label Status Needs label:
|
|
* Code-Review
|
|
* Verified
|
|
----
|
|
|
|
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.png[Adding a Comment]
|
|
|
|
Hannah reviews the change and is ready to provide her feedback. She clicks the
|
|
*REPLY* button on the change screen. This allows her to vote on the change.
|
|
|
|
.Reviewing the Change
|
|
image::images/intro-quick-reviewing-the-change.png[Reviewing the Change]
|
|
|
|
For Hannah and Max's team, a code review vote is 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`
|
|
|
|
In addition, a change must have at least one `+2` vote and no `-2` votes before
|
|
it can be submitted. These numerical values do not accumulate. Two
|
|
`+1` votes do not equate to a `+2`.
|
|
|
|
NOTE: These settings are enabled by default. To learn about how to customize
|
|
them for your own workflow, see the
|
|
link:config-project-config.html[Project Configuration File Format] topic.
|
|
|
|
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
|
|
*SEND* 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's change includes a change-id, all he has to do is follow the typical git
|
|
workflow for updating a commit:
|
|
|
|
* Check out the commit
|
|
* Amend the commit
|
|
* Push the commit to Gerrit
|
|
|
|
----
|
|
$ <checkout first commit>
|
|
$ <rework>
|
|
$ git commit --amend
|
|
[master 30a6f44] Change to a proper, yeast based pizza dough.
|
|
Date: Fri Jun 8 16:28:23 2018 +0200
|
|
1 file changed, 10 insertions(+), 5 deletions(-)
|
|
$ git push origin HEAD:refs/for/master
|
|
Counting objects: 3, done.
|
|
Delta compression using up to 8 threads.
|
|
Compressing objects: 100% (2/2), done.
|
|
Writing objects: 100% (3/3), 528 bytes | 0 bytes/s, done.
|
|
Total 3 (delta 0), reused 0 (delta 0)
|
|
remote: Processing changes: updated: 1, done
|
|
remote:
|
|
remote: Updated Changes:
|
|
remote: http://gerrithost/#/c/RecipeBook/+/702 Change to a proper, yeast based pizza dough.
|
|
remote:
|
|
To ssh://gerrithost:29418/RecipeBook
|
|
* [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, look at his change and diff the first patch set with his rework in
|
|
the second one. Once he has verified that the rework follows Hannahs
|
|
recommendation he presses the *DONE* button to let Hannah know that she can
|
|
review the changes.
|
|
|
|
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.png[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 *SUBMIT* button.
|
|
|
|
At this point, Max's change is merged into the repository's master branch 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
|
|
---------
|