Merge "Replace intro-quick.txt with contents of intro-product-overview.txt"
This commit is contained in:
commit
19cff86d73
@ -5,7 +5,7 @@
|
|||||||
. link:linux-quickstart.html[Quickstart for Installing Gerrit on Linux]
|
. link:linux-quickstart.html[Quickstart for Installing Gerrit on Linux]
|
||||||
|
|
||||||
== About Gerrit
|
== 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-how-gerrit-works.html[How Gerrit Works]
|
||||||
. link:intro-gerrit-walkthrough.html[Basic Gerrit Walkthrough]
|
. 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
|
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
|
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
|
development workflow. It also provides a brief tutorial that shows how to manage
|
||||||
a change using Gerrit.
|
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
|
for Open Source software development, as well as projects where all contributors
|
||||||
are trusted.
|
are trusted.
|
||||||
|
|
||||||
== Gerrit and the developer workflow
|
== Learn About Gerrit
|
||||||
|
|
||||||
To understand how Gerrit fits into and enhances the developer workflow, consider
|
If you're new to Gerrit and want to know more about how it can improve your
|
||||||
a typical project. This project has a central source repository, which serves as
|
developer workflow, see the following topics:
|
||||||
the authoritative copy of the project's contents.
|
|
||||||
|
|
||||||
.Central Source Repository
|
. link:intro-how-gerrit-works.html[How Gerrit Works]
|
||||||
image::images/intro-quick-central-repo.png[Authoritative Source Repository]
|
. link:intro-gerrit-walkthrough.html[Basic Gerrit Walkthrough]
|
||||||
|
|
||||||
Gerrit takes the place of this central repository and adds an additional
|
== Getting Started
|
||||||
concept: a _store of pending changes_.
|
|
||||||
|
|
||||||
.Gerrit in place of Central Repository
|
This documentation contains several guides to help you learn about the Gerrit
|
||||||
image::images/intro-quick-central-gerrit.png[Gerrit in place of Central Repository]
|
features most relevant to you:
|
||||||
|
|
||||||
With Gerrit, when a developer makes a change, it is sent to this store of
|
. link:intro-user.html[User Guide]
|
||||||
pending changes, where other developers can review, discuss and approve the
|
. link:intro-project-owner.html[Project Owner Guide]
|
||||||
change. After enough reviewers grant their approval, the change becomes an
|
. link:https://source.android.com/source/life-of-a-patch[Default Android Workflow] (external)
|
||||||
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
|
|
||||||
|
|
||||||
GERRIT
|
GERRIT
|
||||||
------
|
------
|
||||||
@ -333,3 +37,4 @@ Part of link:index.html[Gerrit Code Review]
|
|||||||
|
|
||||||
SEARCHBOX
|
SEARCHBOX
|
||||||
---------
|
---------
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user