blob: 345eb1cdc4fd52d92b178125977cbdfa742b8cae [file] [log] [blame]
Marian Harbachebeb1542019-12-13 10:42:46 +01001:linkattrs:
David Shevitz42135f92017-07-13 09:52:28 -07002= Working with Gerrit: An example
3
4To understand how Gerrit works, let's follow a change through its entire
5life cycle. This example uses a Gerrit server configured as follows:
6
7* *Hostname*: gerrithost
Sven Selbergd0c00cd2018-06-11 09:05:41 +02008* *HTTP interface port*: 80
David Shevitz42135f92017-07-13 09:52:28 -07009* *SSH interface port*: 29418
10
11In this walkthrough, we'll follow two developers, Max and Hannah, as they make
12and review a change to a +RecipeBook+ project. We'll follow the change through
13these stages:
14
15. Making the change.
16. Creating the review.
17. Reviewing the change.
18. Reworking the change.
19. Verifying the change.
20. Submitting the change.
21
22NOTE: The project and commands used in this section are for demonstration
23purposes only.
24
25== Making the Change
26
27Our first developer, Max, has decided to make a change to the +RecipeBook+
28project he works on. His first step is to get the source code that he wants to
29modify. To get this code, he runs the following `git clone` command:
30
31----
Tao Zhou7c6e3802019-08-02 10:21:57 +020032git clone ssh://gerrithost:29418/RecipeBook.git RecipeBook
David Shevitz42135f92017-07-13 09:52:28 -070033----
34
35After he clones the repository, he runs a couple of commands to add a
36link:user-changeid.html[Change-Id] to his commits. This ID allows Gerrit to link
37together different versions of the same change being reviewed.
38
39....
40scp -p -P 29418 gerrithost:hooks/commit-msg RecipeBook/.git/hooks/
41chmod u+x .git/hooks/commit-msg
42....
43
44NOTE: To learn more about adding a change-id and the commit message hook, see
45the link:cmd-hook-commit-msg.html[commit-msg Hook] topic.
46
47== Creating the Review
48
49Max's next step is to push his change to Gerrit so other contributors can review
50it. He does this using the `git push origin HEAD:refs/for/master` command, as
51follows:
52
53----
54$ <work>
55$ git commit
Sven Selbergd0c00cd2018-06-11 09:05:41 +020056[master 3cc9e62] Change to a proper, yeast based pizza dough.
57 1 file changed, 10 insertions(+), 5 deletions(-)
David Shevitz42135f92017-07-13 09:52:28 -070058$ git push origin HEAD:refs/for/master
Sven Selbergd0c00cd2018-06-11 09:05:41 +020059Counting objects: 3, done.
David Shevitz42135f92017-07-13 09:52:28 -070060Delta compression using up to 8 threads.
61Compressing objects: 100% (2/2), done.
Sven Selbergd0c00cd2018-06-11 09:05:41 +020062Writing objects: 100% (3/3), 532 bytes | 0 bytes/s, done.
David Shevitz42135f92017-07-13 09:52:28 -070063Total 3 (delta 0), reused 0 (delta 0)
Sven Selbergd0c00cd2018-06-11 09:05:41 +020064remote: Processing changes: new: 1, done
David Shevitz42135f92017-07-13 09:52:28 -070065remote:
66remote: New Changes:
Sven Selbergd0c00cd2018-06-11 09:05:41 +020067remote: http://gerrithost/#/c/RecipeBook/+/702 Change to a proper, yeast based pizza dough.
David Shevitz42135f92017-07-13 09:52:28 -070068remote:
Sven Selbergd0c00cd2018-06-11 09:05:41 +020069To ssh://gerrithost:29418/RecipeBook
David Shevitz42135f92017-07-13 09:52:28 -070070 * [new branch] HEAD -> refs/for/master
71----
72
73Notice the reference to a `refs/for/master` branch. Gerrit uses this branch to
74create reviews for the master branch. If Max opted to push to a different
75branch, he would have modified his command to
76`git push origin HEAD:refs/for/<branch_name>`. Gerrit accepts pushes to
77`refs/for/<branch_name>` for every branch that it tracks.
78
79The output of this command also contains a link to a web page Max can use to
80review this commit. Clicking on that link takes him to a screen similar to
81the following.
82
83.Gerrit Code Review Screen
Sven Selbergd0c00cd2018-06-11 09:05:41 +020084image::images/intro-quick-new-review.png[Gerrit Review Screen]
David Shevitz42135f92017-07-13 09:52:28 -070085
86This is the Gerrit code review screen, where other contributors can review
87his change. Max can also perform tasks such as:
88
89* Looking at the link:user-review-ui.html#diff-preferences[diff] of his change
90* Writing link:user-review-ui.html#inline-comments[inline] or
91 link:user-review-ui.html#reply[summary] comments to ask reviewers for advice
92 on particular aspects of the change
93* link:intro-user.html#adding-reviewers[Adding a list of people] that should
94 review the change
95
96In this case, Max opts to manually add the senior developer on his team, Hannah,
97to review his change.
98
99== Reviewing the Change
100
101Let's now switch to Hannah, the senior developer who will review Max's change.
102
103As mentioned previously, Max chose to manually add Hannah as a reviewer. Gerrit
104offers other ways for reviewers to find changes, including:
105
106* Using the link:user-search.html[search] feature that to find changes
107* Selecting *Open* from the *Changes* menu
108* Setting up link:user-notify.html[email notifications] to stay informed of
109 changes even if you are not added as a reviewer
110
111Because Max added Hannah as a reviewer, she receives an email telling her about
112his change. She opens up the Gerrit code review screen and selects Max's change.
113
Sven Selbergd0c00cd2018-06-11 09:05:41 +0200114Notice the *Label status* section above:
David Shevitz42135f92017-07-13 09:52:28 -0700115
116----
Sven Selbergd0c00cd2018-06-11 09:05:41 +0200117Label Status Needs label:
118 * Code-Review
119 * Verified
David Shevitz42135f92017-07-13 09:52:28 -0700120----
121
122These two lines indicate what checks must be completed before the change is
123accepted. The default Gerrit workflow requires two checks:
124
125* *Code-Review*. This check requires that someone look at the code and ensures
126 that it meets project guidelines, styles, and other criteria.
127* *Verified*. This check means that the code actually compiles, passes any unit
128 tests, and performs as expected.
129
130In general, the *Code-Review* check requires an individual to look at the code,
131while the *Verified* check is done by an automated build server, through a
132mechanism such as the
Edwin Kempin862b49e2022-07-13 10:48:45 +0200133link:https://plugins.jenkins.io/gerrit-trigger/[Gerrit Trigger
Marian Harbach34253372019-12-10 18:01:31 +0100134Jenkins Plugin,role=external,window=_blank].
David Shevitz42135f92017-07-13 09:52:28 -0700135
136IMPORTANT: The Code-Review and Verified checks require different permissions
137in Gerrit. This requirement allows teams to separate these tasks. For example,
138an automated process can have the rights to verify a change, but not perform a
139code review.
140
141With the code review screen open, Hannah can begin to review Max's change. She
142can choose one of two ways to review the change: unified or side-by-side.
143Both views allow her to perform tasks such as add
144link:user-review-ui.html#inline-comments[inline] or
145link:user-review-ui.html#reply[summary] comments.
146
147Hannah opts to view the change using Gerrit's side-by-side view:
148
149.Side By Side Patch View
Sven Selbergd0c00cd2018-06-11 09:05:41 +0200150image::images/intro-quick-review-line-comment.png[Adding a Comment]
David Shevitz42135f92017-07-13 09:52:28 -0700151
152Hannah reviews the change and is ready to provide her feedback. She clicks the
Sven Selbergd0c00cd2018-06-11 09:05:41 +0200153*REPLY* button on the change screen. This allows her to vote on the change.
David Shevitz42135f92017-07-13 09:52:28 -0700154
155.Reviewing the Change
Sven Selbergd0c00cd2018-06-11 09:05:41 +0200156image::images/intro-quick-reviewing-the-change.png[Reviewing the Change]
David Shevitz42135f92017-07-13 09:52:28 -0700157
158For Hannah and Max's team, a code review vote is a numerical score between -2
159and 2. The possible options are:
160
161* `+2 Looks good to me, approved`
162* `+1 Looks good to me, but someone else must approve`
163* `0 No score`
Oswald Buddenhagenf8877702022-02-15 14:01:34 +0100164* `-1 I would prefer this is not submitted as is`
165* `-2 This shall not be submitted`
David Shevitz42135f92017-07-13 09:52:28 -0700166
167In addition, a change must have at least one `+2` vote and no `-2` votes before
168it can be submitted. These numerical values do not accumulate. Two
169`+1` votes do not equate to a `+2`.
170
171NOTE: These settings are enabled by default. To learn about how to customize
172them for your own workflow, see the
173link:config-project-config.html[Project Configuration File Format] topic.
174
175Hannah notices a possible issue with Max's change, so she selects a `-1` vote.
176She uses the *Cover Message* text box to provide Max with some additional
177feedback. When she is satisfied with her review, Hannah clicks the
Sven Selbergd0c00cd2018-06-11 09:05:41 +0200178*SEND* button. At this point, her vote and cover message become
David Shevitz42135f92017-07-13 09:52:28 -0700179visible to to all users.
180
181== Reworking the Change
182
183Later in the day, Max decides to check on his change and notices Hannah's
184feedback. He opens up the source file and incorporates her feedback. Because
J. Lewis Muir392bc452018-01-11 11:23:16 -0600185Max's change includes a change-id, all he has to do is follow the typical git
David Shevitz42135f92017-07-13 09:52:28 -0700186workflow for updating a commit:
187
188* Check out the commit
189* Amend the commit
Eryk Szymanskic6664642019-11-11 20:35:17 +0100190* Rebase the commit if needed
David Shevitz42135f92017-07-13 09:52:28 -0700191* Push the commit to Gerrit
192
193----
194$ <checkout first commit>
195$ <rework>
196$ git commit --amend
Sven Selbergd0c00cd2018-06-11 09:05:41 +0200197[master 30a6f44] Change to a proper, yeast based pizza dough.
198 Date: Fri Jun 8 16:28:23 2018 +0200
199 1 file changed, 10 insertions(+), 5 deletions(-)
Eryk Szymanskic6664642019-11-11 20:35:17 +0100200----
201
202At this point Max wants to make sure that his change is on top of the branch.
203
204----
205$ git fetch
206$
207----
208
209Max got no output from the fetch command, which is good news.
210This means that the master branch has not progressed and there is no need for link:intro-user.html#rebase[*rebase*].
211Max is now ready to push his change:
212
213----
David Shevitz42135f92017-07-13 09:52:28 -0700214$ git push origin HEAD:refs/for/master
Sven Selbergd0c00cd2018-06-11 09:05:41 +0200215Counting objects: 3, done.
David Shevitz42135f92017-07-13 09:52:28 -0700216Delta compression using up to 8 threads.
217Compressing objects: 100% (2/2), done.
Sven Selbergd0c00cd2018-06-11 09:05:41 +0200218Writing objects: 100% (3/3), 528 bytes | 0 bytes/s, done.
David Shevitz42135f92017-07-13 09:52:28 -0700219Total 3 (delta 0), reused 0 (delta 0)
220remote: Processing changes: updated: 1, done
221remote:
222remote: Updated Changes:
Sven Selbergd0c00cd2018-06-11 09:05:41 +0200223remote: http://gerrithost/#/c/RecipeBook/+/702 Change to a proper, yeast based pizza dough.
David Shevitz42135f92017-07-13 09:52:28 -0700224remote:
Sven Selbergd0c00cd2018-06-11 09:05:41 +0200225To ssh://gerrithost:29418/RecipeBook
David Shevitz42135f92017-07-13 09:52:28 -0700226 * [new branch] HEAD -> refs/for/master
227----
228
229Notice that the output of this command is slightly different from Max's first
230commit. This time, the output verifies that the change was updated.
231
232Having uploaded the reworked commit, Max can go back to the Gerrit web
Sven Selbergd0c00cd2018-06-11 09:05:41 +0200233interface, look at his change and diff the first patch set with his rework in
234the second one. Once he has verified that the rework follows Hannahs
235recommendation he presses the *DONE* button to let Hannah know that she can
236review the changes.
David Shevitz42135f92017-07-13 09:52:28 -0700237
238When Hannah next looks at Max's change, she sees that he incorporated her
239feedback. The change looks good to her, so she changes her vote to a `+2`.
240
241== Verifying the Change
242
243Hannah's `+2` vote means that Max's change satisfies the *Needs Review*
244check. It has to pass one more check before it can be accepted: the *Needs
245Verified* check.
246
247The Verified check means that the change was confirmed to work. This type of
248check typically involves tasks such as checking that the code compiles, unit
249tests pass, and other actions. You can configure a Verified check to consist
250of as many or as few tasks as needed.
251
252NOTE: Remember that this walkthrough uses Gerrit's default workflow. Projects
253can add custom checks or even remove the Verified check entirely.
254
255Verification is typically an automated process using the
Edwin Kempin862b49e2022-07-13 10:48:45 +0200256link:https://plugins.jenkins.io/gerrit-trigger/[Gerrit Trigger Jenkins Plugin,role=external,window=_blank]
David Shevitz42135f92017-07-13 09:52:28 -0700257or a similar mechanism. However, there are still times when a change requires
258manual verification, or a reviewer needs to check how or if a change works.
259To accommodate these and other similar circumstances, Gerrit exposes each change
260as a git branch. The Gerrit UI includes a
261link:user-review-us.html#download[*download*] link in the Gerrit Code Review
262Screen to make it easy for reviewers to fetch a branch for a specific change.
263To manually verify a change, a reviewer must have the
264link:config-labels.html#label_Verified[Verified] permission. Then, the reviewer
265can fetch and checkout that branch from Gerrit. Hannah has this permission, so
266she is authorized to manually verify Max's change.
267
268NOTE: The Verifier can be the same person as the code reviewer or a
269different person entirely.
270
271.Verifying the Change
Sven Selbergd0c00cd2018-06-11 09:05:41 +0200272image::images/intro-quick-verifying.png[Verifying the Change]
David Shevitz42135f92017-07-13 09:52:28 -0700273
274Unlike the code review check, the verify check is pass/fail. Hannah can provide
275a score of either `+1` or `-1`. A change must have at least one `+1` and no
276`-1`.
277
278Hannah selects a `+1` for her verified check. Max's change is now ready to be
279submitted.
280
281== Submitting the Change
282
283Max is now ready to submit his change. He opens up the change in the Code Review
Sven Selbergd0c00cd2018-06-11 09:05:41 +0200284screen and clicks the *SUBMIT* button.
David Shevitz42135f92017-07-13 09:52:28 -0700285
286At this point, Max's change is merged into the repository's master branch and
287becomes an accepted part of the project.
288
289== Next Steps
290
291This walkthrough provided a quick overview of how a change moves
292through the default Gerrit workflow. At this point, you can:
293
294* Read the link:intro-user.html[Users guide] to get a better sense of how to
295 make changes using Gerrit
296* Review the link:intro-project-owner.html[Project Owners guide] to learn more
297 about configuring projects in Gerrit, including setting user permissions and
298 configuring verification checks
Edwin Kempind54fee72020-05-06 14:04:49 +0200299* Read through the Git and Gerrit training slides that explain concepts and
300 workflows in detail. They are meant for self-studying how Git and Gerrit work:
301** link:https://docs.google.com/presentation/d/1IQCRPHEIX-qKo7QFxsD3V62yhyGA9_5YsYXFOiBpgkk/edit?usp=sharing[Git explained: Git Concepts and Workflows]
302** link:https://docs.google.com/presentation/d/1C73UgQdzZDw0gzpaEqIC6SPujZJhqamyqO1XOHjH-uk/edit?usp=sharing[Gerrit explained: Gerrit Concepts and Workflows]
David Shevitz42135f92017-07-13 09:52:28 -0700303
304GERRIT
305------
306Part of link:index.html[Gerrit Code Review]
307
308SEARCHBOX
309---------