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>

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
 ----------
 

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]