diff options
author | Ed Costello <edc.open@gmail.com> | 2011-07-23 21:38:42 +1200 |
---|---|---|
committer | Martin Fick <mfick@codeaurora.org> | 2011-12-28 12:33:39 -0700 |
commit | d0bc9e56927275538ce57200fdc1a8280f1c0995 (patch) | |
tree | 205b1d7e201d9b60608ce2e5a53e4d0ae00b13a9 | |
parent | 8fa3d26d4383a80f68e32661c71844f73a0339c4 (diff) |
First Cut of Gerrit Walkthrough Introduction documentation.
Intended to be a complement for the existing reference documentation to allow
potential users to easily get a feel for how Gerrit is used, where it fits
and whether it will work for them.
Change-Id: Ibbbba36873ee9185d5998eb337b26cc7761b215e
Signed-off-by: Fredrik Luthander <fredrik.luthander@sonyericsson.com>
-rw-r--r-- | Documentation/images/intro-quick-central-gerrit.dia | bin | 0 -> 2206 bytes | |||
-rw-r--r-- | Documentation/images/intro-quick-central-gerrit.png | bin | 0 -> 31846 bytes | |||
-rw-r--r-- | Documentation/images/intro-quick-central-repo.dia | bin | 0 -> 1498 bytes | |||
-rw-r--r-- | Documentation/images/intro-quick-central-repo.png | bin | 0 -> 15534 bytes | |||
-rw-r--r-- | Documentation/images/intro-quick-hot-key-help.jpg | bin | 0 -> 107554 bytes | |||
-rw-r--r-- | Documentation/images/intro-quick-new-review.jpg | bin | 0 -> 84230 bytes | |||
-rw-r--r-- | Documentation/images/intro-quick-review-2-patches.jpg | bin | 0 -> 89542 bytes | |||
-rw-r--r-- | Documentation/images/intro-quick-review-line-comment.jpg | bin | 0 -> 91119 bytes | |||
-rw-r--r-- | Documentation/images/intro-quick-reviewing-the-change.jpg | bin | 0 -> 50477 bytes | |||
-rw-r--r-- | Documentation/images/intro-quick-verifying.jpg | bin | 0 -> 61485 bytes | |||
-rw-r--r-- | Documentation/index.txt | 5 | ||||
-rw-r--r-- | Documentation/intro-quick.txt | 390 |
12 files changed, 395 insertions, 0 deletions
diff --git a/Documentation/images/intro-quick-central-gerrit.dia b/Documentation/images/intro-quick-central-gerrit.dia Binary files differnew file mode 100644 index 0000000000..8192ba98dd --- /dev/null +++ b/Documentation/images/intro-quick-central-gerrit.dia diff --git a/Documentation/images/intro-quick-central-gerrit.png b/Documentation/images/intro-quick-central-gerrit.png Binary files differnew file mode 100644 index 0000000000..61b9638e6e --- /dev/null +++ b/Documentation/images/intro-quick-central-gerrit.png diff --git a/Documentation/images/intro-quick-central-repo.dia b/Documentation/images/intro-quick-central-repo.dia Binary files differnew file mode 100644 index 0000000000..9916dbbbd0 --- /dev/null +++ b/Documentation/images/intro-quick-central-repo.dia diff --git a/Documentation/images/intro-quick-central-repo.png b/Documentation/images/intro-quick-central-repo.png Binary files differnew file mode 100644 index 0000000000..84ffeb02a5 --- /dev/null +++ b/Documentation/images/intro-quick-central-repo.png diff --git a/Documentation/images/intro-quick-hot-key-help.jpg b/Documentation/images/intro-quick-hot-key-help.jpg Binary files differnew file mode 100644 index 0000000000..41bcbe4aed --- /dev/null +++ b/Documentation/images/intro-quick-hot-key-help.jpg diff --git a/Documentation/images/intro-quick-new-review.jpg b/Documentation/images/intro-quick-new-review.jpg Binary files differnew file mode 100644 index 0000000000..99e6c55661 --- /dev/null +++ b/Documentation/images/intro-quick-new-review.jpg diff --git a/Documentation/images/intro-quick-review-2-patches.jpg b/Documentation/images/intro-quick-review-2-patches.jpg Binary files differnew file mode 100644 index 0000000000..29c99cc94b --- /dev/null +++ b/Documentation/images/intro-quick-review-2-patches.jpg diff --git a/Documentation/images/intro-quick-review-line-comment.jpg b/Documentation/images/intro-quick-review-line-comment.jpg Binary files differnew file mode 100644 index 0000000000..eeb144af2d --- /dev/null +++ b/Documentation/images/intro-quick-review-line-comment.jpg diff --git a/Documentation/images/intro-quick-reviewing-the-change.jpg b/Documentation/images/intro-quick-reviewing-the-change.jpg Binary files differnew file mode 100644 index 0000000000..bfded9eab4 --- /dev/null +++ b/Documentation/images/intro-quick-reviewing-the-change.jpg diff --git a/Documentation/images/intro-quick-verifying.jpg b/Documentation/images/intro-quick-verifying.jpg Binary files differnew file mode 100644 index 0000000000..7679c0a548 --- /dev/null +++ b/Documentation/images/intro-quick-verifying.jpg diff --git a/Documentation/index.txt b/Documentation/index.txt index 1ad51a3e9e..b2cc9dccec 100644 --- a/Documentation/index.txt +++ b/Documentation/index.txt @@ -1,6 +1,11 @@ Gerrit Code Review for Git ========================== +Getting Started +--------------- + +* link:intro-quick.html[A Quick Introduction To Gerrit] + User Guide ---------- diff --git a/Documentation/intro-quick.txt b/Documentation/intro-quick.txt new file mode 100644 index 0000000000..3d5cbcbb00 --- /dev/null +++ b/Documentation/intro-quick.txt @@ -0,0 +1,390 @@ +Gerrit Code Review - A Quick Introduction +========================================= + +Gerrit is a web-based code review tool built on top of the git version +control system, but if you've got as far as reading this guide then +you probably already know that. The purpose of this introduction is to +allow you to answer the question, is Gerrit the right tool for me? +Will it fit in my work flow and in my organization? + +What is Gerrit? +--------------- + +I assume that if you're reading this then you're already convinced of +the benefits of code review in general but want some technical support +to make it easy. Code reviews mean different things to different people. +To some it's a formal meeting with a projector and an entire team +going through the code line by line. To others it's getting someone to +glance over the code before it is committed. + +Gerrit is intended to provide a light weight framework for reviewing +every commit before it is accepted into the code base. Changes are +uploaded to Gerrit but don't actually become a part of the project +until they've been reviewed and accepted. In many ways this is simply +tooling to support the standard open source process of submitting +patches which are then reviewed by the project members before being +applied to the code base. However Gerrit goes a step further making it +simple for all committers on a project to ensure that changes are +checked over before they're actually applied. Because of this Gerrit +is equally useful where all users are trusted committers such as may +the case with closed-source commercial development. Either way it's +still desirable to have code reviewed to improve the quality and +maintainability of the code. After all, if only one person has seen +the code it may be a little difficult to maintain when that person +leaves. + +Gerrit is firstly a staging area where changes can be checked over +before becoming a part of the code base. It is also an enabler for +this review process, capturing notes and comments about the changes to +enable discussion of the change. This is particularly useful with +distributed teams where this conversation can't happen face to face. +Even with a co-located team having a review tool as an option is +beneficial because reviews can be done at a time that is convenient +for the reviewer. This allows the developer to create the review and +explain the change while it is fresh in their mind. Without such a +tool they either need to interrupt someone to review the code or +switch context to explain the change when they've already moved on to +the next task. + +This also creates a lasting record of the conversation which can be +useful for answering the inevitable "I know we changed this for a +reason" questions. + +Where does Gerrit fit in? +------------------------- + +Any team with more than one member has a central source repository of +some kind (or they should). Git can theoretically work without such a +central location but in practice there is usually a central +repository. This serves as the authoritative copy of what is actually in +the project. This is what everyone fetches from and pushes to and is +generally where build servers and other such tools get the source +from. + +.Central Source Repository +image::images/intro-quick-central-repo.png[Authoritative Source Repository] + +Gerrit is deployed in place of this central repository and adds an +additional concept, a store of pending changes. Everyone still fetches +from the authoritative repository but instead of pushing back to it, +they push to this pending changes location. A change can only be submitted +into the authoritative repository and become an accepted part of the project +once the change has been reviewed and approved. + +.Gerrit in place of Central Repository +image::images/intro-quick-central-gerrit.png[Gerrit in place of Central Repository] + +Like any repository hosting solution, Gerrit has a powerful +link:access-control.html[access control model.] +Users can even be granted access to push directly into the central +repository, bypassing code review entirely. Gerrit can even be used +without code review, used simply to host the repositories and +controlling access. But generally it's just simpler and safer to go +through the review process even for users who are allowed to directly +push. + +The Life and Times of a Change +------------------------------ + +The easiest way to get a feel for how Gerrit works is to follow a +change through its entire life cycle. For the purpose of this example +we'll assume that the Gerrit Server is running on a server called ++gerrithost+ with the HTTP interface on port +8080+ and the SSH +interface on port +29418+. The project we'll be working on is called ++RecipeBook+ and we'll be developing a change for the +master+ branch. + +Cloning the Repository +~~~~~~~~~~~~~~~~~~~~~~ + +Obviously the first thing we need to do is get the source that we're +going to be modifying. As with any git project you do this by cloning +the central repository that Gerrit is hosting. e.g. + +---- +$ git clone ssh://gerrithost:29418/RecipeBook.git RecipeBook +Cloning into RecipeBook... +---- + +Then we need to make our actual change and commit it locally. Gerrit +doesn't really change anything here, this is just the standard editing +and git. While not strictly required, it's best to include a Change-Id +in your commit message so that Gerrit can link together different +versions of the same change being reviewed. Gerrit contains a standard +link:user-changeid.html[Change-Id commit-msg hook] +that will generate a unique Change-Id when you commit. If you don't do +this then Gerrit will generate a Change-Id when you push your change +for review. But because you don't have the Change-Id in your commit +message you'll need to manually copy it in if you need to upload +another version of your change. Because of this it's best to just +install the hook and forget about it. + +Creating the Review +~~~~~~~~~~~~~~~~~~~ + +Once you've made your change and committed it locally it's time to +push it to Gerrit so that it can be reviewed. This is done with a git +push to the Gerrit server. Since we cloned our local repository +directly from Gerrit it is the origin so we don't have to redefine the +remote. + +---- +$ <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 only different thing about this is the +refs/for/master+ branch. +This is a magic branch that creates reviews that target the master +branch. For every branch Gerrit tracks there is a magic ++refs/for/<branch_name>+ that you push to to create reviews. + +In the output of this command you'll notice that there is a link to +the HTTP interface of the Gerrit server we just pushed to. This is the +web interface where we will review this commit. Let's follow that link +and see what we get. + +.Gerrit Code Review Screen +image::images/intro-quick-new-review.jpg[Gerrit Review Screen] + +This is the Gerrit code review screen where someone will come to +review the change. There isn't too much to see here yet, you can look +at the diff of your change, add some comments explaining what you did +and why, you may even add a list of people that should review the change. + +Reviewers can find changes that they want to review in any number of +ways. Gerrit has a capable +link:user-search.html[search] +that allows project leaders (or anyone else) to find changes that need +to be reviewed. Users can also setup watches on Gerrit projects with a +search expression, this causes Gerrit to notify them of matching +changes. So adding a reviewer when creating a review is just a +recommendation. + +At this point the change is available for review and we need to switch +roles to continue following the change. Now let's pretend we're the +reviewer. + +Reviewing the Change +~~~~~~~~~~~~~~~~~~~~ + +The reviewer's life starts at the code review screen shown above. He +can get here in a number of ways, but for some reason they've decided +to review this change. Of particular note on this screen are the two +"Need" lines: + +---- +* Need Verified +* Need Code-Review +---- + +Gerrit's default work-flow requires two checks before a change is +accepted. Code-Review is someone looking at the code, ensuring it +meets the project guidelines, intent etc. Verifying is checking that +the code actually compiles, unit tests pass etc. Verification is +usually done by an automated build server rather than a person. There +is even a +link:https://wiki.jenkins-ci.org/display/JENKINS/Gerrit+Trigger[Gerrit Trigger Jenkins Plugin] +that will automatically build each uploaded change and update the +verified score accordingly. + +It is important to note that Code-Review and Verification are +different permissions in Gerrit, allowing these tasks to be separated. +For example, an automated process would have rights to verify but not +to code-review. + +Since we are the code reviewer, we're going to review the code. To do +this we can view it within the Gerrit web interface as either a +unified or side-by-side diff by selecting the appropriate option. In +the example below we've selected the side-by-side view. In either of +these views you can add comments by double clicking on the line (or +single click the line number) that you want to comment on. Once +published these comments are viewable to all, allowing discussion +of the change to take place. + +.Side By Side Patch View +image::images/intro-quick-review-line-comment.jpg[Adding a Comment] + +Code reviewers end up spending a lot of time navigating these screens, +looking at and commenting on these changes. To make this as efficient +as possible Gerrit has keyboard shortcuts for most operations (and +even some operations that are only accessible via the hot-keys). At +any time you can hit the +?+ key to see the keyboard shortcuts. + +.Gerrit Hot Key Help +image::images/intro-quick-hot-key-help.jpg[Hot Key Help] + +Once we've looked over the changes we need to complete reviewing the +submission. To do this we click the _Review_ button on the change +screen where we started. This allows us to enter a Code Review label +and message. + +.Reviewing the Change +image::images/intro-quick-reviewing-the-change.jpg[Reviewing the Change] + +The label that the reviewer selects determines what can happen next. +The +1 and -1 level are just an opinion where as the +2 and -2 levels +are allowing or blocking the change. In order for a change to be +accepted it must have at least one +2 and no -2 votes. +Although these are numeric values, they in no way accumulate; +two +1s do not equate to a +2. + +Regardless of what label is selected, once the _Publish Comments_ +button has been clicked, the cover message and any comments on the +files become visible to all users. + +In this case the change was not accepted so the creator needs to +rework it. So let's switch roles back to the creator where we +started. + +Reworking the Change +~~~~~~~~~~~~~~~~~~~~ + +As long as we set up the +link:user-changeid.html[Change-Id commit-msg hook] +before we uploaded the change, re-working it is easy. All we need +to do to upload a re-worked change is to push another commit that has +the same Change-Id in the message. Since the hook added a Change-ID in +our initial commit we can simply checkout and then amend that commit. +Then push it to Gerrit in the same way as we did to create the review. E.g. + +---- +$ <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) +To ssh://gerrithost:29418/RecipeBook.git + * [new branch] HEAD -> refs/for/master +---- + +Note that the output is slightly different this time around. We don't +get told about a new review because we're adding to an existing +review. Having uploaded the reworked commit we can go back into the +Gerrit web interface and look at our change. + +.Reviewing the Rework +image::images/intro-quick-review-2-patches.jpg[Reviewing the Rework] + +If you look closely you'll notice that there are now two patch sets +associated with this change, the initial submission and the rework. +Rather than repeating ourselves lets assume that this time around the +patch is given a +2 score by the code reviewer. + +Trying out the Change +~~~~~~~~~~~~~~~~~~~~~ + +With Gerrit's default work-flow there are two sign-offs, code review +and verify. Verifying means checking that the change actually works. +This would typically be checking that the code compiles, unit tests +pass and similar checks. Really a project can decide how much or +little they want to do here. It's also worth noting that this is only +Gerrit's default work-flow, the verify check can actually be removed +or others added. + +As mentioned in the code review section, verification is typically an +automated process using the +link:https://wiki.jenkins-ci.org/display/JENKINS/Gerrit+Trigger[Gerrit Trigger Jenkins Plugin] +or similar. But there are times when the code needs to be manually +verified, or the reviewer needs to check that something actually works +or how it works. Sometimes it's just nice to work through the code in a +development environment rather than the web interface. All of these +involve someone needing to get the change into their development +environment. Gerrit makes this process easy by exposing each change as +a git branch. So all the reviewers need to do is fetch and checkout that +branch from Gerrit and they will have the change. + +We don't even need to think about it that hard, if you look at the +earlier screen shots of the Gerrit Code Review Screen you'll notice a +_download_ command. All we need to do to get the change is copy +paste this command and run it in our Gerrit checkout. + +---- +$ git fetch http://gerrithost:8080/p/RecipeBook refs/changes/68/68/2 +From http://gerrithost:8080/p/RecipeBook + * branch refs/changes/68/68/2 -> FETCH_HEAD +$ git checkout FETCH_HEAD +Note: checking out 'FETCH_HEAD'. + +You are in 'detached HEAD' state. You can look around, make experimental +changes and commit them, and you can discard any commits you make in this +state without impacting any branches by performing another checkout. + +If you want to create a new branch to retain commits you create, you may +do so (now or later) by using -b with the checkout command again. Example: + + git checkout -b new_branch_name + +HEAD is now at d5dacdb... Change to a proper, yeast based pizza dough. +---- + +Easy as that, we now have the change in our working copy to play with. +You might be interested in what the numbers of the refspec mean. + +* The first *68* is the id if the change +mod 100+. The only reason +for this initial number is to reduce the number of files in any given +directory within the git repository. +* The second *68* is the full id of the change. You'll notice this in +the URL of the Gerrit review screen. +* The *2* is the patch-set within the change. In this example we +uploaded some fixes so we want the second patch set rather than the +initial one which the reviewer rejected. + +Manually Verifying the Change +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For simplicity we're just going to manually verify the change. +The Verifier may be the same person as the code reviewer or a +different person entirely. It really depends on the size of the +project and what works. If you have Verify permission then when you +click the _Review_ button in the Gerrit web interface you'll be +presented with a verify score. + +.Verifying the Change +image::images/intro-quick-verifying.jpg[Verifying the Change] + +Unlike the code review the verify check doesn't have a +2 or -2 level, +it's either a pass or fail so all we need for the change to be +submitted is a +1 score (and no -1's). + +Submitting the Change +~~~~~~~~~~~~~~~~~~~~~ + +You might have noticed that in the verify screen shot there are two +buttons for submitting the score _Publish Comments_ and _Publish +and Submit_. The publish and submit button is always visible, but will +only work if the change meets the criteria for being submitted (I.e. +has been both verified and code reviewed). So it's a convenience to be +able to post review scores as well as submitting the change by clicking +a single button. If you choose just to publish comments at this point then +the score will be stored but the change won't yet be accepted into the code +base. In this case there will be a _Submit Patch Set X_ button on the +main screen. Just as Code Review and Verify are different operations +that can be done by different users, Submission is a third operation +that can be limited down to another group of users. + +Activating the _Publish and Submit_ or _Submit Patch Set X_ button +will merge the change into the main part of the repository so that it +becomes an accepted part of the project. After this anyone fetching +the git repository will receive this change as a part of the master +branch. + +GERRIT +------ +Part of link:index.html[Gerrit Code Review] |