Documentation/intro-quick.txt - gerrit - Git at Google

 = Gerrit Code Review - A Quick Introduction

 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.

 == Gerrit and the developer workflow

 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.

 .Central Source Repository
 image::images/intro-quick-central-repo.png[Authoritative Source Repository]

 Gerrit takes the place of this central repository and adds an additional
 concept: a _store of pending changes_.

 .Gerrit in place of Central Repository
 image::images/intro-quick-central-gerrit.png[Gerrit in place of Central Repository]

 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

 GERRIT
 ------
 Part of link:index.html[Gerrit Code Review]

 SEARCHBOX
 ---------
	= Gerrit Code Review - A Quick Introduction

	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.

	== Gerrit and the developer workflow

	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.

	.Central Source Repository
	image::images/intro-quick-central-repo.png[Authoritative Source Repository]

	Gerrit takes the place of this central repository and adds an additional
	concept: a _store of pending changes_.

	.Gerrit in place of Central Repository
	image::images/intro-quick-central-gerrit.png[Gerrit in place of Central Repository]

	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

	GERRIT
	------
	Part of link:index.html[Gerrit Code Review]

	SEARCHBOX
	---------