Marian Harbach | ebeb154 | 2019-12-13 10:42:46 +0100 | [diff] [blame] | 1 | :linkattrs: |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 2 | = Working with Gerrit: An example |
| 3 | |
| 4 | To understand how Gerrit works, let's follow a change through its entire |
| 5 | life cycle. This example uses a Gerrit server configured as follows: |
| 6 | |
| 7 | * *Hostname*: gerrithost |
Sven Selberg | d0c00cd | 2018-06-11 09:05:41 +0200 | [diff] [blame] | 8 | * *HTTP interface port*: 80 |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 9 | * *SSH interface port*: 29418 |
| 10 | |
| 11 | In this walkthrough, we'll follow two developers, Max and Hannah, as they make |
| 12 | and review a change to a +RecipeBook+ project. We'll follow the change through |
| 13 | these 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 | |
| 22 | NOTE: The project and commands used in this section are for demonstration |
| 23 | purposes only. |
| 24 | |
| 25 | == Making the Change |
| 26 | |
| 27 | Our first developer, Max, has decided to make a change to the +RecipeBook+ |
| 28 | project he works on. His first step is to get the source code that he wants to |
| 29 | modify. To get this code, he runs the following `git clone` command: |
| 30 | |
| 31 | ---- |
Tao Zhou | 7c6e380 | 2019-08-02 10:21:57 +0200 | [diff] [blame] | 32 | git clone ssh://gerrithost:29418/RecipeBook.git RecipeBook |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 33 | ---- |
| 34 | |
| 35 | After he clones the repository, he runs a couple of commands to add a |
| 36 | link:user-changeid.html[Change-Id] to his commits. This ID allows Gerrit to link |
| 37 | together different versions of the same change being reviewed. |
| 38 | |
| 39 | .... |
| 40 | scp -p -P 29418 gerrithost:hooks/commit-msg RecipeBook/.git/hooks/ |
| 41 | chmod u+x .git/hooks/commit-msg |
| 42 | .... |
| 43 | |
| 44 | NOTE: To learn more about adding a change-id and the commit message hook, see |
| 45 | the link:cmd-hook-commit-msg.html[commit-msg Hook] topic. |
| 46 | |
| 47 | == Creating the Review |
| 48 | |
| 49 | Max's next step is to push his change to Gerrit so other contributors can review |
| 50 | it. He does this using the `git push origin HEAD:refs/for/master` command, as |
| 51 | follows: |
| 52 | |
| 53 | ---- |
| 54 | $ <work> |
| 55 | $ git commit |
Sven Selberg | d0c00cd | 2018-06-11 09:05:41 +0200 | [diff] [blame] | 56 | [master 3cc9e62] Change to a proper, yeast based pizza dough. |
| 57 | 1 file changed, 10 insertions(+), 5 deletions(-) |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 58 | $ git push origin HEAD:refs/for/master |
Sven Selberg | d0c00cd | 2018-06-11 09:05:41 +0200 | [diff] [blame] | 59 | Counting objects: 3, done. |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 60 | Delta compression using up to 8 threads. |
| 61 | Compressing objects: 100% (2/2), done. |
Sven Selberg | d0c00cd | 2018-06-11 09:05:41 +0200 | [diff] [blame] | 62 | Writing objects: 100% (3/3), 532 bytes | 0 bytes/s, done. |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 63 | Total 3 (delta 0), reused 0 (delta 0) |
Sven Selberg | d0c00cd | 2018-06-11 09:05:41 +0200 | [diff] [blame] | 64 | remote: Processing changes: new: 1, done |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 65 | remote: |
| 66 | remote: New Changes: |
Sven Selberg | d0c00cd | 2018-06-11 09:05:41 +0200 | [diff] [blame] | 67 | remote: http://gerrithost/#/c/RecipeBook/+/702 Change to a proper, yeast based pizza dough. |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 68 | remote: |
Sven Selberg | d0c00cd | 2018-06-11 09:05:41 +0200 | [diff] [blame] | 69 | To ssh://gerrithost:29418/RecipeBook |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 70 | * [new branch] HEAD -> refs/for/master |
| 71 | ---- |
| 72 | |
| 73 | Notice the reference to a `refs/for/master` branch. Gerrit uses this branch to |
| 74 | create reviews for the master branch. If Max opted to push to a different |
| 75 | branch, 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 | |
| 79 | The output of this command also contains a link to a web page Max can use to |
| 80 | review this commit. Clicking on that link takes him to a screen similar to |
| 81 | the following. |
| 82 | |
| 83 | .Gerrit Code Review Screen |
Sven Selberg | d0c00cd | 2018-06-11 09:05:41 +0200 | [diff] [blame] | 84 | image::images/intro-quick-new-review.png[Gerrit Review Screen] |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 85 | |
| 86 | This is the Gerrit code review screen, where other contributors can review |
| 87 | his 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 | |
| 96 | In this case, Max opts to manually add the senior developer on his team, Hannah, |
| 97 | to review his change. |
| 98 | |
| 99 | == Reviewing the Change |
| 100 | |
| 101 | Let's now switch to Hannah, the senior developer who will review Max's change. |
| 102 | |
| 103 | As mentioned previously, Max chose to manually add Hannah as a reviewer. Gerrit |
| 104 | offers 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 | |
| 111 | Because Max added Hannah as a reviewer, she receives an email telling her about |
| 112 | his change. She opens up the Gerrit code review screen and selects Max's change. |
| 113 | |
Sven Selberg | d0c00cd | 2018-06-11 09:05:41 +0200 | [diff] [blame] | 114 | Notice the *Label status* section above: |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 115 | |
| 116 | ---- |
Sven Selberg | d0c00cd | 2018-06-11 09:05:41 +0200 | [diff] [blame] | 117 | Label Status Needs label: |
| 118 | * Code-Review |
| 119 | * Verified |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 120 | ---- |
| 121 | |
| 122 | These two lines indicate what checks must be completed before the change is |
| 123 | accepted. 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 | |
| 130 | In general, the *Code-Review* check requires an individual to look at the code, |
| 131 | while the *Verified* check is done by an automated build server, through a |
| 132 | mechanism such as the |
Edwin Kempin | 862b49e | 2022-07-13 10:48:45 +0200 | [diff] [blame] | 133 | link:https://plugins.jenkins.io/gerrit-trigger/[Gerrit Trigger |
Marian Harbach | 3425337 | 2019-12-10 18:01:31 +0100 | [diff] [blame] | 134 | Jenkins Plugin,role=external,window=_blank]. |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 135 | |
| 136 | IMPORTANT: The Code-Review and Verified checks require different permissions |
| 137 | in Gerrit. This requirement allows teams to separate these tasks. For example, |
| 138 | an automated process can have the rights to verify a change, but not perform a |
| 139 | code review. |
| 140 | |
| 141 | With the code review screen open, Hannah can begin to review Max's change. She |
| 142 | can choose one of two ways to review the change: unified or side-by-side. |
| 143 | Both views allow her to perform tasks such as add |
| 144 | link:user-review-ui.html#inline-comments[inline] or |
| 145 | link:user-review-ui.html#reply[summary] comments. |
| 146 | |
| 147 | Hannah opts to view the change using Gerrit's side-by-side view: |
| 148 | |
| 149 | .Side By Side Patch View |
Sven Selberg | d0c00cd | 2018-06-11 09:05:41 +0200 | [diff] [blame] | 150 | image::images/intro-quick-review-line-comment.png[Adding a Comment] |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 151 | |
| 152 | Hannah reviews the change and is ready to provide her feedback. She clicks the |
Sven Selberg | d0c00cd | 2018-06-11 09:05:41 +0200 | [diff] [blame] | 153 | *REPLY* button on the change screen. This allows her to vote on the change. |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 154 | |
| 155 | .Reviewing the Change |
Sven Selberg | d0c00cd | 2018-06-11 09:05:41 +0200 | [diff] [blame] | 156 | image::images/intro-quick-reviewing-the-change.png[Reviewing the Change] |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 157 | |
| 158 | For Hannah and Max's team, a code review vote is a numerical score between -2 |
| 159 | and 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 Buddenhagen | f887770 | 2022-02-15 14:01:34 +0100 | [diff] [blame] | 164 | * `-1 I would prefer this is not submitted as is` |
| 165 | * `-2 This shall not be submitted` |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 166 | |
| 167 | In addition, a change must have at least one `+2` vote and no `-2` votes before |
| 168 | it can be submitted. These numerical values do not accumulate. Two |
| 169 | `+1` votes do not equate to a `+2`. |
| 170 | |
| 171 | NOTE: These settings are enabled by default. To learn about how to customize |
| 172 | them for your own workflow, see the |
| 173 | link:config-project-config.html[Project Configuration File Format] topic. |
| 174 | |
| 175 | Hannah notices a possible issue with Max's change, so she selects a `-1` vote. |
| 176 | She uses the *Cover Message* text box to provide Max with some additional |
| 177 | feedback. When she is satisfied with her review, Hannah clicks the |
Sven Selberg | d0c00cd | 2018-06-11 09:05:41 +0200 | [diff] [blame] | 178 | *SEND* button. At this point, her vote and cover message become |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 179 | visible to to all users. |
| 180 | |
| 181 | == Reworking the Change |
| 182 | |
| 183 | Later in the day, Max decides to check on his change and notices Hannah's |
| 184 | feedback. He opens up the source file and incorporates her feedback. Because |
J. Lewis Muir | 392bc45 | 2018-01-11 11:23:16 -0600 | [diff] [blame] | 185 | Max's change includes a change-id, all he has to do is follow the typical git |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 186 | workflow for updating a commit: |
| 187 | |
| 188 | * Check out the commit |
| 189 | * Amend the commit |
Eryk Szymanski | c666464 | 2019-11-11 20:35:17 +0100 | [diff] [blame] | 190 | * Rebase the commit if needed |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 191 | * Push the commit to Gerrit |
| 192 | |
| 193 | ---- |
| 194 | $ <checkout first commit> |
| 195 | $ <rework> |
| 196 | $ git commit --amend |
Sven Selberg | d0c00cd | 2018-06-11 09:05:41 +0200 | [diff] [blame] | 197 | [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 Szymanski | c666464 | 2019-11-11 20:35:17 +0100 | [diff] [blame] | 200 | ---- |
| 201 | |
| 202 | At this point Max wants to make sure that his change is on top of the branch. |
| 203 | |
| 204 | ---- |
| 205 | $ git fetch |
| 206 | $ |
| 207 | ---- |
| 208 | |
| 209 | Max got no output from the fetch command, which is good news. |
| 210 | This means that the master branch has not progressed and there is no need for link:intro-user.html#rebase[*rebase*]. |
| 211 | Max is now ready to push his change: |
| 212 | |
| 213 | ---- |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 214 | $ git push origin HEAD:refs/for/master |
Sven Selberg | d0c00cd | 2018-06-11 09:05:41 +0200 | [diff] [blame] | 215 | Counting objects: 3, done. |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 216 | Delta compression using up to 8 threads. |
| 217 | Compressing objects: 100% (2/2), done. |
Sven Selberg | d0c00cd | 2018-06-11 09:05:41 +0200 | [diff] [blame] | 218 | Writing objects: 100% (3/3), 528 bytes | 0 bytes/s, done. |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 219 | Total 3 (delta 0), reused 0 (delta 0) |
| 220 | remote: Processing changes: updated: 1, done |
| 221 | remote: |
| 222 | remote: Updated Changes: |
Sven Selberg | d0c00cd | 2018-06-11 09:05:41 +0200 | [diff] [blame] | 223 | remote: http://gerrithost/#/c/RecipeBook/+/702 Change to a proper, yeast based pizza dough. |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 224 | remote: |
Sven Selberg | d0c00cd | 2018-06-11 09:05:41 +0200 | [diff] [blame] | 225 | To ssh://gerrithost:29418/RecipeBook |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 226 | * [new branch] HEAD -> refs/for/master |
| 227 | ---- |
| 228 | |
| 229 | Notice that the output of this command is slightly different from Max's first |
| 230 | commit. This time, the output verifies that the change was updated. |
| 231 | |
| 232 | Having uploaded the reworked commit, Max can go back to the Gerrit web |
Sven Selberg | d0c00cd | 2018-06-11 09:05:41 +0200 | [diff] [blame] | 233 | interface, look at his change and diff the first patch set with his rework in |
| 234 | the second one. Once he has verified that the rework follows Hannahs |
| 235 | recommendation he presses the *DONE* button to let Hannah know that she can |
| 236 | review the changes. |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 237 | |
| 238 | When Hannah next looks at Max's change, she sees that he incorporated her |
| 239 | feedback. The change looks good to her, so she changes her vote to a `+2`. |
| 240 | |
| 241 | == Verifying the Change |
| 242 | |
| 243 | Hannah's `+2` vote means that Max's change satisfies the *Needs Review* |
| 244 | check. It has to pass one more check before it can be accepted: the *Needs |
| 245 | Verified* check. |
| 246 | |
| 247 | The Verified check means that the change was confirmed to work. This type of |
| 248 | check typically involves tasks such as checking that the code compiles, unit |
| 249 | tests pass, and other actions. You can configure a Verified check to consist |
| 250 | of as many or as few tasks as needed. |
| 251 | |
| 252 | NOTE: Remember that this walkthrough uses Gerrit's default workflow. Projects |
| 253 | can add custom checks or even remove the Verified check entirely. |
| 254 | |
| 255 | Verification is typically an automated process using the |
Edwin Kempin | 862b49e | 2022-07-13 10:48:45 +0200 | [diff] [blame] | 256 | link:https://plugins.jenkins.io/gerrit-trigger/[Gerrit Trigger Jenkins Plugin,role=external,window=_blank] |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 257 | or a similar mechanism. However, there are still times when a change requires |
| 258 | manual verification, or a reviewer needs to check how or if a change works. |
| 259 | To accommodate these and other similar circumstances, Gerrit exposes each change |
| 260 | as a git branch. The Gerrit UI includes a |
| 261 | link:user-review-us.html#download[*download*] link in the Gerrit Code Review |
| 262 | Screen to make it easy for reviewers to fetch a branch for a specific change. |
| 263 | To manually verify a change, a reviewer must have the |
| 264 | link:config-labels.html#label_Verified[Verified] permission. Then, the reviewer |
| 265 | can fetch and checkout that branch from Gerrit. Hannah has this permission, so |
| 266 | she is authorized to manually verify Max's change. |
| 267 | |
| 268 | NOTE: The Verifier can be the same person as the code reviewer or a |
| 269 | different person entirely. |
| 270 | |
| 271 | .Verifying the Change |
Sven Selberg | d0c00cd | 2018-06-11 09:05:41 +0200 | [diff] [blame] | 272 | image::images/intro-quick-verifying.png[Verifying the Change] |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 273 | |
| 274 | Unlike the code review check, the verify check is pass/fail. Hannah can provide |
| 275 | a score of either `+1` or `-1`. A change must have at least one `+1` and no |
| 276 | `-1`. |
| 277 | |
| 278 | Hannah selects a `+1` for her verified check. Max's change is now ready to be |
| 279 | submitted. |
| 280 | |
| 281 | == Submitting the Change |
| 282 | |
| 283 | Max is now ready to submit his change. He opens up the change in the Code Review |
Sven Selberg | d0c00cd | 2018-06-11 09:05:41 +0200 | [diff] [blame] | 284 | screen and clicks the *SUBMIT* button. |
David Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 285 | |
| 286 | At this point, Max's change is merged into the repository's master branch and |
| 287 | becomes an accepted part of the project. |
| 288 | |
| 289 | == Next Steps |
| 290 | |
| 291 | This walkthrough provided a quick overview of how a change moves |
| 292 | through 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 Kempin | d54fee7 | 2020-05-06 14:04:49 +0200 | [diff] [blame] | 299 | * 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 Shevitz | 42135f9 | 2017-07-13 09:52:28 -0700 | [diff] [blame] | 303 | |
| 304 | GERRIT |
| 305 | ------ |
| 306 | Part of link:index.html[Gerrit Code Review] |
| 307 | |
| 308 | SEARCHBOX |
| 309 | --------- |