Replace intro-quick.txt with contents of intro-product-overview.txt
Also update link in index.txt. With this change, users won't get confused by having two different introductory topics. See change 113490 for additional details on intro-product-overview topic. Change-Id: Ieb0fb4c89a315c12f43cb7a2aba7f92476cdb3ea
This commit is contained in:
parent
36d668a68d
commit
c94cf4acd3
@ -5,7 +5,7 @@
|
||||
. link:linux-quickstart.html[Quickstart for Installing Gerrit on Linux]
|
||||
|
||||
== About Gerrit
|
||||
. link:intro-product-overview.html[Product Overview]
|
||||
. link:intro-quick.html[Product Overview]
|
||||
. link:intro-how-gerrit-works.html[How Gerrit Works]
|
||||
. link:intro-gerrit-walkthrough.html[Basic Gerrit Walkthrough]
|
||||
|
||||
|
@ -1,40 +0,0 @@
|
||||
= Gerrit Product Overview
|
||||
|
||||
Gerrit is a web-based code review tool built on top of the
|
||||
https://git-scm.com/[Git version control system]. This introduction provides
|
||||
an overview of Gerrit and describes how Gerrit integrates into a typical
|
||||
development workflow. It also provides a brief tutorial that shows how to manage
|
||||
a change using Gerrit.
|
||||
|
||||
== What is Gerrit?
|
||||
|
||||
Gerrit makes code review easy by providing a lightweight framework for reviewing
|
||||
commits before they are accepted by the codebase. Gerrit works equally well for
|
||||
projects where approving changes is restricted to selected users, as is typical
|
||||
for Open Source software development, as well as projects where all contributors
|
||||
are trusted.
|
||||
|
||||
== Learn About Gerrit
|
||||
|
||||
If you're new to Gerrit and want to know more about how it can improve your
|
||||
developer workflow, see the following topics:
|
||||
|
||||
. link:intro-product-overview.html[Product Overview]
|
||||
. link:intro-gerrit-walkthrough.html[Basic Gerrit Walkthrough]
|
||||
|
||||
== Getting Started
|
||||
|
||||
This documentation contains several guides to help you learn about the Gerrit
|
||||
features most relevant to you:
|
||||
|
||||
. link:intro-user.html[User Guide]
|
||||
. link:intro-project-owner.html[Project Owner Guide]
|
||||
. link:http://source.android.com/submit-patches/workflow[Default Android Workflow] (external)
|
||||
|
||||
GERRIT
|
||||
------
|
||||
Part of link:index.html[Gerrit Code Review]
|
||||
|
||||
SEARCHBOX
|
||||
---------
|
||||
|
@ -1,7 +1,7 @@
|
||||
= Gerrit Code Review - A Quick Introduction
|
||||
= Gerrit Product Overview
|
||||
|
||||
Gerrit is a web-based code review tool built on top of the
|
||||
https://git-scm.com/[git version control system]. This introduction provides
|
||||
https://git-scm.com/[Git version control system]. This introduction provides
|
||||
an overview of Gerrit and describes how Gerrit integrates into a typical
|
||||
development workflow. It also provides a brief tutorial that shows how to manage
|
||||
a change using Gerrit.
|
||||
@ -14,318 +14,22 @@ projects where approving changes is restricted to selected users, as is typical
|
||||
for Open Source software development, as well as projects where all contributors
|
||||
are trusted.
|
||||
|
||||
== Gerrit and the developer workflow
|
||||
== Learn About Gerrit
|
||||
|
||||
To understand how Gerrit fits into and enhances the developer workflow, consider
|
||||
a typical project. This project has a central source repository, which serves as
|
||||
the authoritative copy of the project's contents.
|
||||
If you're new to Gerrit and want to know more about how it can improve your
|
||||
developer workflow, see the following topics:
|
||||
|
||||
.Central Source Repository
|
||||
image::images/intro-quick-central-repo.png[Authoritative Source Repository]
|
||||
. link:intro-how-gerrit-works.html[How Gerrit Works]
|
||||
. link:intro-gerrit-walkthrough.html[Basic Gerrit Walkthrough]
|
||||
|
||||
Gerrit takes the place of this central repository and adds an additional
|
||||
concept: a _store of pending changes_.
|
||||
== Getting Started
|
||||
|
||||
.Gerrit in place of Central Repository
|
||||
image::images/intro-quick-central-gerrit.png[Gerrit in place of Central Repository]
|
||||
This documentation contains several guides to help you learn about the Gerrit
|
||||
features most relevant to you:
|
||||
|
||||
With Gerrit, when a developer makes a change, it is sent to this store of
|
||||
pending changes, where other developers can review, discuss and approve the
|
||||
change. After enough reviewers grant their approval, the change becomes an
|
||||
official part of the codebase.
|
||||
|
||||
In addition to this store of pending changes, Gerrit captures notes
|
||||
and comments about each change. These features allow developers to review
|
||||
changes at their convenience, or when conversations about a change can't
|
||||
happen face to face. They also help to create a record of the conversation
|
||||
around a given change, which can provide a history of when a change was made and
|
||||
why.
|
||||
|
||||
Like any repository hosting solution, Gerrit has a powerful
|
||||
link:access-control.html[access control model.] This model allows you to
|
||||
fine-tune access to your repository.
|
||||
|
||||
== 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*: 8080
|
||||
* *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
|
||||
Cloning into RecipeBook...
|
||||
----
|
||||
|
||||
After he clones the repository, he makes a change to the file and commits it
|
||||
locally.
|
||||
|
||||
NOTE: At this point, the workflow is exactly the same as it would be if Max was
|
||||
not using Gerrit.
|
||||
|
||||
Max is ready to create a commit message for his change. When he does, he
|
||||
includes a link:user-changeid.html[Change-Id]. This ID allows Gerrit to link
|
||||
together different versions of the same change being reviewed.
|
||||
|
||||
=== 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 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 `refs/for/master` branch is a symbolic branch that Gerrit uses 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 automatically creates a
|
||||
`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.jpg[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 explain what he did and
|
||||
why
|
||||
* 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
|
||||
* 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.
|
||||
|
||||
.Gerrit Code Review Screen
|
||||
image::images/intro-quick-new-review.jpg[Gerrit Review Screen]
|
||||
|
||||
Notice the two "Need" lines:
|
||||
|
||||
----
|
||||
* Need Verified
|
||||
* Need Code-Review
|
||||
----
|
||||
|
||||
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.jpg[Adding a Comment]
|
||||
|
||||
Hannah reviews the change and is ready to provide her feedback. She clicks the
|
||||
*Review* button on the change screen. This allows her to vote on the change.
|
||||
|
||||
.Reviewing the Change
|
||||
image::images/intro-quick-reviewing-the-change.jpg[Reviewing the Change]
|
||||
|
||||
A code review vote is essentially 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`
|
||||
|
||||
By default, a change must have at least one `+2` vote and no `-2` votes before
|
||||
it can be submitted.
|
||||
|
||||
IMPORTANT: Although votes use numerical values, they do not accumulate. Two
|
||||
`+1` votes do not equate to a `+2`.
|
||||
|
||||
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
|
||||
*Published Comments* 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 set up the link:user-changeid.html[Change-Id commit-msg hook]
|
||||
before he uploaded the change, all he has to do to upload the re-worked change
|
||||
is push another commit with the same Change-Id in the message. To accomplish
|
||||
this, Max needs only perform the following tasks:
|
||||
|
||||
* Check out the commit
|
||||
* Amend the commit
|
||||
* Push the commit to Gerrit
|
||||
|
||||
----
|
||||
$ <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)
|
||||
remote: Processing changes: updated: 1, done
|
||||
remote:
|
||||
remote: Updated Changes:
|
||||
remote: http://gerrithost:8080/68
|
||||
remote:
|
||||
To ssh://gerrithost:29418/RecipeBook.git
|
||||
* [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 and look at his change.
|
||||
|
||||
.Reviewing the Rework
|
||||
image::images/intro-quick-review-2-patches.jpg[Reviewing the Rework]
|
||||
|
||||
Notice that there are now two patch sets associated with this change: the
|
||||
initial submission and the rework.
|
||||
|
||||
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.jpg[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 *Publish and Submit* button.
|
||||
|
||||
At this point, Max's change is merged into the main part of the repository 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
|
||||
. link:intro-user.html[User Guide]
|
||||
. link:intro-project-owner.html[Project Owner Guide]
|
||||
. link:https://source.android.com/source/life-of-a-patch[Default Android Workflow] (external)
|
||||
|
||||
GERRIT
|
||||
------
|
||||
@ -333,3 +37,4 @@ Part of link:index.html[Gerrit Code Review]
|
||||
|
||||
SEARCHBOX
|
||||
---------
|
||||
|
||||
|
Loading…
x
Reference in New Issue
Block a user