Documentation/intro-gerrit-walkthrough-github.txt

:linkattrs:
= Basic Gerrit Walkthrough -- For GitHub Users


[NOTE]
====
This document aims to provide a concise description of the core principles of
code review in Gerrit for people that were previously using Pull Requests on
Github or similar concepts. Nothing in this document is meant to state that
one or the other might be better, but only aims to help new users understand
Gerrit more readily. We use Github as the point of comparison since it seems
to be the most popular service.
====

To illustrate the differences in a meaningful order, we will walk you through
the process of cloning a repo, making a change, asking for code review,
iterating on the code and finally having it submitted to the code base. This
document also does not aim to describe all features of Gerrit. Please refer to
the link:intro-gerrit-walkthrough.html[Basic Gerrit Walkthrough] or
link:index.html[the rest of the documentation] for a more complete overview and additional pointers.

[[tldr]]
== tl;dr

Here’s how getting code reviewed and submitted with Gerrit is different from
doing the same with GitHub:

* You need to add a commit-msg hook script when you clone a repo for the first
time using a snippet you can find e.g. https://gerrit-review.googlesource.com/admin/repos/gerrit[here,role=external,window=_blank];
* Your review will be on a single commit instead of a branch. You use
`git commit --amend` to modify a code change.
* Instead of using the Web UI to create a pull request, you use
`git push origin HEAD:refs/for/master` to upload new local commits that are
ready for review to Gerrit. You will find the URL to the review in the output of
the push command.
* As a reviewer, Gerrit offers a number of so-called labels to vote on, one of
which is Code-Review. You indicate a negative, neutral or positive review using
a -1, 0 or +1 vote.
* To be able to submit (== merge) a change, you usually need a +2 Code-Review
vote and possibly additional positive votes, depending on the configuration of
the project you are contributing to.

[[clone]]
== 1. Cloning a Repository

[NOTE]
====
Both GitHub and Gerrit provide simple Git repository hosting (of course both can
do much more). In the simplest setup, you could just use both as such without
any code review to push code. We will assume that this is not what you want to
do and focus on the use case where your change requires a review.
====

The first step to working with the code is to clone the repo. For both, Gerrit
and GitHub, you can simply use the `git clone` command.

For Gerrit, there is an additional step before you can start making changes. For
reasons we explain below, you’ll have to add a https://gerrit-review.googlesource.com/Documentation/user-changeid.html[commit-msg hook,role=external,window=_blank] script. This will
append the Gerrit Change-Id to every commit message such that Gerrit can track
commits through the review process. To make this process a little easier in
Gerrit, you can find a command snippet for cloning and adding the commit-msg
hook on the repository page (e.g. https://gerrit-review.googlesource.com/admin/repos/gerrit[here,role=external,window=_blank]).

[[create-change]]
== 2. Making a Change

*Branches*

Now that you have the code in the git repo on your machine, you can start making
changes. With GitHub, you would usually create a new branch and then start
committing to it. This branch would then contain all the changes you share with
your code reviewers in the next step. Your local branch will usually also be
pushed to the remote server. This can be handy to back up your work or hand-off
work to another device or developer.

With Gerrit, you can also create a new local branch to develop in. While not
required, it can be considered a best practice to sandbox this change from other
changes you might be making. In contrast to the GitHub model, your local branch
will not have to be pushed to the remote in Gerrit, at least not for the
purposes of code review.

*Commits*
In Gerrit, a single commit is the unit of code that will be reviewed. With
GitHub, you can commit to your branch as much as you like and the sum of all
your commits on that branch will get reviewed. As a single commit gets reviewed
in Gerrit, you need to `git commit --amend` when you iterate on the same change as
opposed to only using `git commit` with GitHub (see Section 5 for more). You can,
however, also add another commit on top of your existing commit in Gerrit, which
will create a second change (and thus another review) that is based on your
first change. Gerrit will show the relationship between these two changes as a
so-called relation chain. This also means that your second change can only be
submitted after the first was successfully merged. In many basic use cases, this
situation is however not what you want.

image::images/user-review-ui-change-relation-chain.png[Relation chain display on the change page.]

With GitHub, you may be pushing your branch to the remote for non-code-review
purposes, as mentioned above. You usually do not do this with Gerrit, as
Gerrit-managed repos often only have one or a few branches on the server that
can only be merged into via code review.

[[request-review]]
== 3. Asking for Code Review

After you are satisfied with the changes you made, you’ll usually want/need to
get your code reviewed. In GitHub, you would push your branch to the remote, go
to the Web UI and create a pull request. In Gerrit, you need to push your commit
(or the series of changes/commits) to the remote first, since you usually
develop in a local branch only. While you can often just use git push with
GitHub, you need to do a slightly different thing for Gerrit. Gerrit uses a
“magic” branch that tells the server that this code is supposed to be reviewed.
To send the changes you made on your local branch to review and being eventually
merged into the remote’s master branch, you use
`git push origin HEAD:refs/for/master`. There are also link:user-upload.html#_git_push[a number of Gerrit change
options] you can trigger from the CLI this way.

After successfully pushing your change to Gerrit, you will already find the URL
for viewing your change in Gerrit’s Web UI in the response you get from the
server. The description of the Gerrit code review that was just created is equal
to the commit message of that one commit the change is based on. In GitHub, you
might have described your change in the message you can create when creating the
pull request in the GitHub Web UI.

Next, you would go and visit your Gerrit change in the Web UI to get your change
ready for review (choose reviewers, cc people, check for failing CI builds or
tests, etc.), very similar to what you do on Github. Reviewers will be notified
via email once you add them. By default, anyone can add reviewers to a Gerrit
change. In GitHub, this ability is reserved for certain users, so you may have
relied on others adding reviewers for you before. This can be the case in a
Gerrit project, but it is also often expected that the change owner (usually the
creator of the change) adds reviewers to get the review process started.

[[reviewing]]
== 4. Reviewing a Change

Switching perspectives briefly, reviewing a change is fairly similar between
GitHub and Gerrit. You, as a reviewer, will be notified of a change you have
been added to via email or see an “incoming” change on your Gerrit dashboard.
The dashboard is the central overview of changes going on within a Gerrit
instance. By default, the dashboard shows changes that you are involved in, in
any way. You can also see all changes on a Gerrit server by using the top menu
(“Changes” -> “Open”). This view is more similar to what you see on Github, when
you navigate to the Pull Requests tab of the project/repository you are working
on. Note, however, that a single Gerrit instance can host multiple projects
(also referred to as repositories; a list can be found, for example, https://gerrit-review.googlesource.com/admin/repos[here,role=external,window=_blank]). Your
dashboard and other lists of changes will show all changes across the
projects/repositories by default.

Back to your dashboard, you can click on the change you want to review. You can
also access this from the email you received. You will see the same view that
you saw as an author. In the middle of the change page, you can find the list of
files that have been modified, just like what you find in the “Files changed”
tab of GitHub. Also similarly, you can leave comments by highlighting a piece of
the code and pressing ‘c’. All comments you make are in a draft state and thus
only visible to you, like on GitHub. When you are done with your review, you
need to click the “Reply” button at the top of the change page to send your
assessment to the change owner alongside a “change message” summarizing your
findings and/or adding higher level comments. Replying to a change makes your
draft comments and the change message visible on the change page for everyone
that has view access to this change. This again is fairly similar to GitHub,
except for Gerrit’s voting labels.

image::images/user-review-ui-change-reply-dialogue.png[Reply dialogue for a Gerrit change.]

As you can see in the screenshot of the reply dialogue, the voting labels are in
the bottom part of the dialogue. They can be fairly simple as in this case, but
there can also be a larger number of labels you might be able to vote on. Labels
can be used to distinguish different aspects of a review (e.g. whether or not
the licensing of included libraries is okay), outcome of CI systems (e.g.
whether or not a format checker passed, a build completed successfully, etc.) or
as a flag that is read by bots to do something with a change. An example of a
more complex label setup can be seen in this screenshot from the Android Gerrit
instance.

image::images/user-review-ui-change-complex-reply-dialogue.png[Reply dialogue for a change on the Android project.]

In the simplest case shown above, voting -1 on the Code-Review label equals
requesting changes on a GitHub pull request, 0 equals just having comments and
+1 means that you think this change looks good. Usually, Gerrit changes require
a +2 vote on the Code-Review label to be submitted (merged in GitHub terms, see
Section 6 below). Being able to vote +2 on Code-Review is often restricted to
maintainers of a given project, so they can have a final say on a change. These
practices can however vary between projects, as labels and voting permissions
are configurable.

[[iterate]]
== 5. Iterating on the Change

After your reviewers got back to you as a change owner, you realize that you
need to make a few updates to the code in your change. As mentioned in Section 2
(Making a Change), you’ll have to amend the commit that this review was based
on. To do that, you might have to checkout the respective commit first if it is
not at the tip of your local branch, for example if you stacked multiple changes
on top of each other. Another common use case is to not have a local branch but
to work in the so-called https://www.git-tower.com/learn/git/faq/detached-head-when-checkout-commit["detached HEAD",role=external,window=_blank] mode. In that case you can use the
“Download” button on the files tab to copy a command that fetches and checks out
the commit underlying your change. Make sure to select the latest patchset,
though!

image::images/user-review-ui-change-page-download.png[Using the “Download” button to copy a command that checks out a given patchset for a change.]

After checking out the commit, you then make the changes as usual. When you
think you are done, you can commit with the `--amend` flag to change the commit
you currently have checked out.

When you `git commit --amend` to iterate on your change, you might be worried that
you are changing your previous commit and may thus lose that state of your work.
However, here the Change-Id appended to your commit message comes into play.
While the SHA-1 hash of your change (the commit ID used by Git) might change, the
Change-Id stays the same (in fact it is the SHA-1 hash of the very first version
of that commit). When this amended commit is uploaded to the Gerrit server,
Gerrit knows that this commit is really an iteration of that previous commit
(and the associated review) and will preserve both, the old and the new state.
All previous states of your commit will be visible in the Gerrit UI as so-called
patchsets (and link:intro-user.html#change-ref[from the Git repo]).

image::images/user-review-ui-change-page-patchset-dropdown.png[Screenshot of the patchset dropdown above the file list, showing all iterations a commit went through.]

After iterating as much as needed, your reviewers will finally be satisfied.
With GitHub, you would have a string of additional commits in the branch you
used for opening the pull request. In Gerrit, you still only have that one
commit in your local branch. All the iterations are available as patchsets in
the Web UI as well as from the special branch mentioned above.

[[submit]]
== 6. Submitting a Change

Finally, it is time to submit your change. As mentioned above, the precondition
for this in Gerrit is usually at least a +2 vote on the Code-Review label. With
GitHub, an authorized person must have given an “Approve” vote. Once this
precondition has been met, anyone with submit permission can submit the change
in Gerrit. To do that, you click the “Submit” button in the Gerrit Web UI just
as you would click the “Merge Pull Request” button in GitHub. Both, Gerrit and
GitHub, allow different merge strategies, that can be enabled by project
administrators. In Gerrit, a merge strategy is configured for each project and
cannot be changed at submit time while this may be possible with GitHub,
depending on project configuration.

A merge can fail due to conflicts with competing edits on the target branch.
With GitHub, you may be able to resolve some simple conflicts directly from the
Web UI. In Gerrit, you can attempt to rebase a change from the Web UI. If there
are no conflicts, a new patchset will automatically appear. Otherwise, similar
to GitHub, you need to resolve conflicts on the command line with your local
clone of the repository. While you resolve conflicts that arise from a
`git merge` for GitHub, you will need to link:intro-user.html#rebase[use `git rebase` with your change] on
Gerrit.

After resolving locally, with GitHub, you end up with another commit on your
pull request branch and push it to the server, which should then allow you to
finish merging the change. With Gerrit, resolving the conflict through rebasing
your commit/change results in another amended version of that same commit and
you upload it to Gerrit, resulting in a new patchset just like your previous
iterations addressing reviewer comments. This new patchset will usually require
another round of reviewer votes, as Gerrit will not copy votes from a previous
patchset by default.


GERRIT
------

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

SEARCHBOX
---------