Difference between revisions of "Development/Gerrit"

 
(18 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
== Getting Started ==
 
== Getting Started ==
  
Gerrit is a tool for web-based code review -- similar to [[Development/ReviewBoard|ReviewBoard]], but better in many ways.
+
Gerrit is a tool for web-based code review -- similar to ReviewBoard, but with some neat features. For instance, it has built-in CI bot (Code Integration) support and general workflow is integrated with Git. It's used for patch submission to Trojitá.  
  
The first step is to active your account at Gerrit. Use your KDE Identity account to [https://gerrit.vesnicky.cesnet.cz/r/login/ log in]. Go into [https://gerrit.vesnicky.cesnet.cz/r/#/settings/ssh-keys Settings -> SSH Keys] and upload your public SSH key in there.
+
The first step is logging in. Use your [https://identity.kde.org/ KDE Identity] account (or [https://identity.kde.org/index.php?r=registration/index get one here]) to [https://gerrit.vesnicky.cesnet.cz/r/login/ log in to Gerrit]. Go into [https://gerrit.vesnicky.cesnet.cz/r/#/settings/ssh-keys Settings -> SSH Keys] and upload your public SSH key in there. If you don't have these so far, you need to create one. For starters, there is a [[Development/Tutorials/Git/GitQuickStart|Git QuickStart Guide]] that will help you to create SSH keys and clone KDE repository you are interested in. Also be sure to [[Development/Tutorials/Git/Create_a_patch|configure your name and e-mail in git]] before you proceed.
  
Patches can be uploaded for review by any KDE user (users and developers alike). Here are a couple of one-time fixes to get you started. We will assume that your repository is already cloned from KDE (FIXME: do we want to prefer clones from Gerrit for some reason? I don't think so.)
+
Patches can be uploaded for review by any KDE user with legit Identity account, so you are not obligated to have a KDE Developer account at all. Here is a little hint to get started. We will assume that your repository is already cloned from KDE servers. Take a note that you obviously need to do this once per repo.
  
 
   # At first, let's add a new git remote
 
   # At first, let's add a new git remote
Line 12: Line 12:
 
   scp -p -P 29418 '''YourKdeIdentityUsername'''@gerrit.vesnicky.cesnet.cz:hooks/commit-msg .git/hooks/
 
   scp -p -P 29418 '''YourKdeIdentityUsername'''@gerrit.vesnicky.cesnet.cz:hooks/commit-msg .git/hooks/
  
=== Submitting Changes: git gpush ===
+
=== Submitting Changes to Gerrit ===
  
There are a couple of options of how to use Gerrit from now on. The first one is to use a handy script by Qt's developers.  
+
So you've got some code changes now and you want to submit these into a Change. Good practice is to use "topic branch here" and do everything in it, so you don't affect any remote branches. Simply make commits (one per change) and when you're done, push them to a "magic ref". Instead of doing stuff like <tt>git push gerrit master</tt>, you do:
FIXME: http://lists.qt-project.org/pipermail/development/2012-April/003427.html
 
  
=== Submitting Changes: Manual Setup ===
+
  git push gerrit HEAD:refs/for/master
  
Another option is doing everything by hand. Simply make commits and when you're done, push them to a "magic ref". Instead of doing stuff like <tt>git push gerrit master</tt>, you do:
+
The above will open a review request(s) on top of master, one for each commit that you made.
  
  git push gerrit master:refs/for/master
+
The key point is the <tt>'''refs/for/'''</tt> prefix. This is a magic ref, or a magic branch. It does not really exist on-disk, but whenever you push there, Gerrit notices that you want to update or create a new patch/change/request/... and do the right thing.
  
If you're working on a local feature branch, you can achieve a similar result by something like this:
+
Gerrit will tell you what has happened -- either everything went well and then you got a link to a change request on the web, or something broke and then you should get an error message about what was it. There are also advanced possibilities, see further down in this page for them.
  
  git push gerrit HEAD:refs/for/master
+
=== Reviewing Changes ===
  
The above will open a review request on top of master, so clicking "Submit" will merge the whole branch into master.
+
Since many users, who mess up with not trivial Gerrit UI, you should see the [https://gerrit.vesnicky.cesnet.cz/r/Documentation/user-review-ui.html documentation on how to work with the web UI], or an
If you instead want to open a review request against a feature branch and want to push on that remote branch itself you do instead (in this example the branch is called mybranch)
+
[http://gerrit-review.googlesource.com/Documentation/intro-quick.html#_reviewing_the_change older basic tutorial] if you want to deal with everything UI-related.
  
  git push gerrit HEAD:refs/for/mybranch
+
Any registered user can give you +1 .. -1 points for ''Code Review''. KDE developers can give you +2 .. -2 points for any review request. Your change becomes submittable when it has at least single +2 grade and there are no -2 "veto" reviews.
  
The key point is the <tt>'''refs/for/'''</tt> prefix. This is a magic ref, or a magic branch. It does not really exist, but whenever you push to it, Gerrit notices that you want to update or create a new patch/change/request/... and do the right thing.
+
=== Modifying Changes ===
  
Gerrit will tell you what has happened -- either everything went well and then you got a link to a change request on the web, or something broke and then you should get an error message about what was it.
+
Just amend/rebase/modify-in-any-other-way your commit and push to <tt>refs/for/'''targetBranchName'''</tt>. Here is a way to do this with <tt>amend</tt>:
  
You can also add reviewers from here. To add three people, <tt>[email protected]</tt>, <tt>[email protected]</tt> and <tt>[email protected]</tt>, do it like this:
+
  # Make some changes over existing commit
 +
  git add -u
 +
  git commit --amend
 +
  git push gerrit HEAD:/refs/for/'''targetBranchName'''
  
  git push gerrit HEAD:refs/for/master'''%[email protected].org,[email protected],[email protected]'''
+
As long as the <tt>Change-Id</tt> line in the commit is preserved, Gerrit will do the right thing and notice that it's an updated version of an existing change.
  
As usual, the <tt>git gpush</tt> thingy is more user friendly, supports not only e-mails but also nicks, etc.
+
=== Receiving Notifications ===
  
=== Reviewing Changes ===
+
Go to [https://gerrit.vesnicky.cesnet.cz/r/#/settings/projects settings], add a project, and then ''make sure all checkboxes are ticked''. The default operation adds a project to your watchlist, but no events would be delivered to you.
  
See the guide at [http://gerrit-review.googlesource.com/Documentation/intro-quick.html#_reviewing_the_change Gerrit's website] for a basic tutorial. Any registered user can give a +1 .. -1 for ''Code Review''. KDE developers can give +2 .. -2 for any review request. At least one +2 and zero -2s are needed for a change to be submittable.
+
Please note that this is a pretty recent version of Gerrit which differs in a few ways from the version used by e.g. the Qt project. Most of the changes are in the UI, e.g. to apply stuff locally, use the '''Download''' menu at the top-right corner of the change view.
 
 
=== Modifying Changes ===
 
  
Just amend/rebase/modify-in-any-other-way your commit and push to <tt>refs/for/'''targetBranchName'''</tt>. As long as the <tt>Change-Id</tt> line in the commit is preserved, Gerrit will do the right thing and notice that it's an updated version of an existing change.
+
=== Advanced: Using gpush ===
 
 
=== Receiving Notifications ===
 
  
Go to [https://gerrit.vesnicky.cesnet.cz/r/#/settings/projects settings], add a project, and then ''make sure all checkboxes are ticked''. The default operation adds a project to your watchlist, but no events would be delivered to you :(.
+
Gerrit works well out-of-the-box with regular git functionality, but for some advanced usage, you might want to use script by Qt's developers -- <tt>gpush</tt>. It provides smart interface to some Gerrit features. You can get it along with [https://qt.gitorious.org/qt/qtrepotools qtrepotools] from official Qt repository. Just make sure that its '''bin''' directory is in '''$PATH'''. Here are some examples of its usage:
  
Please note that this is a pretty recent version of Gerrit which differs in a few ways from the version used by e.g. the Qt project. Most of the changes are in the UI, e.g. to apply stuff locally, use the '''Download''' menu at the top-right corner of the change view.
+
  # Pushes HEAD:refs/for/'''branch''' to 'gerrit' without any reviewers
 +
  git gpush
 +
  # Pushes HEAD:refs/for/$TRB to 'gerrit', adding mariuso as a reviewer
 +
  # and sends thiago a CC mail
 +
  git gpush +mariuso =thiago
 +
  # Pushes HEAD:refs/for/buildsystem to 'gerrit', no reviewers
 +
  git gpush :refs/for/buildsystem
  
 
== Nice Tweaks ==
 
== Nice Tweaks ==
Line 93: Line 97:
 
   git config remote.gerrit.push refs/heads/*:refs/for/*
 
   git config remote.gerrit.push refs/heads/*:refs/for/*
 
   git push gerrit
 
   git push gerrit
 +
 +
=== Specifying reviewers when pushing ===
 +
 +
You can also add reviewers while you submit stuff for review. To add three people, <tt>[email protected]</tt>, <tt>[email protected]</tt> and <tt>[email protected]</tt>, do it like this:
 +
 +
  git push gerrit HEAD:refs/for/master'''%[email protected],[email protected],[email protected]'''
 +
 +
At these points you can clearly see advantages of <tt>git gpush</tt> script, because it's more user friendly and supports nicknames along with emails as well.
  
 
=== Anything Else? ===
 
=== Anything Else? ===
Line 99: Line 111:
  
 
What tricks do you find neat?
 
What tricks do you find neat?
 
== BoF at Akademy ==
 
Someone suggested to use [https://community.kde.org/Frameworks/Meetings/201409Akademy Frameworks Meeting] (Room 1 - September 9th, afternoon).
 
 
Also the PIM one (Room 4 - September 9th, morning)
 
  
 
== Sysadmin Stuff ==
 
== Sysadmin Stuff ==
Line 111: Line 118:
 
The name of the project repository at KDE's git and in gerrit have to match. One can only add regular project repositories, not personal clones or scratch repos.
 
The name of the project repository at KDE's git and in gerrit have to match. One can only add regular project repositories, not personal clones or scratch repos.
  
At first, setup the project in Gerrit:
+
At first, set up KDE's infrastructure so that any pushes propagate to Gerrit:
 
 
  ssh -p 29418 gerrit.vesnicky.cesnet.cz gerrit create-project --parent sysadmin/gerrit-kde-traditional-projects '''NameOfGitRepo'''
 
 
 
Now set up KDE's infrastructure so that any pushes propagate to Gerrit:
 
  
 
   cd kde/repo-management
 
   cd kde/repo-management
 
   # do an equivalent of commit 6bd604f73902d9a14c05a2abb88da5e1838ce2ea
 
   # do an equivalent of commit 6bd604f73902d9a14c05a2abb88da5e1838ce2ea
   echo ssh://[email protected]:29418/'''YourRepoName''' > repo-configs/remote-update/'''YourRepoName'''.git
+
   echo ssh://[email protected]:29418/'''YourRepoName''' \
 +
    > repo-configs/remote-update/'''YourRepoName'''.git
 
   git commit -a
 
   git commit -a
 
   git push
 
   git push
  
At this point, you can either wait for any push to KDE's git, or push the data yourself. The manual options needs special access, though. Do '''not''' push to <tt>refs/for/*</tt>, do something like <tt>git push gerrit master:refs/heads/master</tt> and <tt>git push gerrit --tags</tt>.
+
Now setup the project in Gerrit:
 +
 
 +
  ssh -p 29418 gerrit.vesnicky.cesnet.cz gerrit create-project \
 +
    --parent sysadmin/gerrit-kde-traditional-projects '''NameOfGitRepo'''
 +
 
 +
This creates a <tt>refs/meta/config</tt> branch within Gerrit's git copy, which gets pushed to git.kde.org, which in turn notices that it should push missing branches to Gerrit, and stuff just works from that time on.
  
 
=== How Stuff Works ===
 
=== How Stuff Works ===
Line 130: Line 139:
  
 
== TODO list ==
 
== TODO list ==
* Documentation: Write a howto for users/developers
+
* Documentation: Write a howto for users/developers (this page)
 
* Define how to get support
 
* Define how to get support
 +
** through IRC at <tt>#kde-sysadmin</tt> on freenode (ping <tt>jkt</tt>)
 
** sysadmin's tickets?
 
** sysadmin's tickets?
 
*** gerrit admins have to be able to read these
 
*** gerrit admins have to be able to read these
Line 138: Line 148:
 
** Frederik Gladhorn -- done
 
** Frederik Gladhorn -- done
 
** Ben Cooksley -- done
 
** Ben Cooksley -- done
** vblazquez?
+
** vblazquez -- done
 
** tosky?
 
** tosky?
 
** Who else? Register at Gerrit, send a mail to [mailto:[email protected] jkt] and I'll make it happen.
 
** Who else? Register at Gerrit, send a mail to [mailto:[email protected] jkt] and I'll make it happen.
* take care of regular backups
+
* Improve the CI
** PostgreSQL DB
 
** git's refs/changes/*
 
* Implement the CI
 
** Jenkins, its job builder, zuul,...
 
 
** Tool idea: run krazy over submitted patches before committing and inform committer about possible changes
 
** Tool idea: run krazy over submitted patches before committing and inform committer about possible changes
 
* Get SSH keys from LDAP ([http://code.google.com/p/gerrit/issues/detail?id=1124 bugreport])
 
* Get SSH keys from LDAP ([http://code.google.com/p/gerrit/issues/detail?id=1124 bugreport])

Latest revision as of 16:19, 22 September 2017

Getting Started

Gerrit is a tool for web-based code review -- similar to ReviewBoard, but with some neat features. For instance, it has built-in CI bot (Code Integration) support and general workflow is integrated with Git. It's used for patch submission to Trojitá.

The first step is logging in. Use your KDE Identity account (or get one here) to log in to Gerrit. Go into Settings -> SSH Keys and upload your public SSH key in there. If you don't have these so far, you need to create one. For starters, there is a Git QuickStart Guide that will help you to create SSH keys and clone KDE repository you are interested in. Also be sure to configure your name and e-mail in git before you proceed.

Patches can be uploaded for review by any KDE user with legit Identity account, so you are not obligated to have a KDE Developer account at all. Here is a little hint to get started. We will assume that your repository is already cloned from KDE servers. Take a note that you obviously need to do this once per repo.

 # At first, let's add a new git remote
 git remote add gerrit ssh://YourKdeIdentityUsername@gerrit.vesnicky.cesnet.cz:29418/RepositoryName
 # Gerrit needs a client-side hook for putting the Change-Id tags into commit messages
 scp -p -P 29418 YourKdeIdentityUsername@gerrit.vesnicky.cesnet.cz:hooks/commit-msg .git/hooks/

Submitting Changes to Gerrit

So you've got some code changes now and you want to submit these into a Change. Good practice is to use "topic branch here" and do everything in it, so you don't affect any remote branches. Simply make commits (one per change) and when you're done, push them to a "magic ref". Instead of doing stuff like git push gerrit master, you do:

 git push gerrit HEAD:refs/for/master

The above will open a review request(s) on top of master, one for each commit that you made.

The key point is the refs/for/ prefix. This is a magic ref, or a magic branch. It does not really exist on-disk, but whenever you push there, Gerrit notices that you want to update or create a new patch/change/request/... and do the right thing.

Gerrit will tell you what has happened -- either everything went well and then you got a link to a change request on the web, or something broke and then you should get an error message about what was it. There are also advanced possibilities, see further down in this page for them.

Reviewing Changes

Since many users, who mess up with not trivial Gerrit UI, you should see the documentation on how to work with the web UI, or an older basic tutorial if you want to deal with everything UI-related.

Any registered user can give you +1 .. -1 points for Code Review. KDE developers can give you +2 .. -2 points for any review request. Your change becomes submittable when it has at least single +2 grade and there are no -2 "veto" reviews.

Modifying Changes

Just amend/rebase/modify-in-any-other-way your commit and push to refs/for/targetBranchName. Here is a way to do this with amend:

 # Make some changes over existing commit
 git add -u
 git commit --amend
 git push gerrit HEAD:/refs/for/targetBranchName

As long as the Change-Id line in the commit is preserved, Gerrit will do the right thing and notice that it's an updated version of an existing change.

Receiving Notifications

Go to settings, add a project, and then make sure all checkboxes are ticked. The default operation adds a project to your watchlist, but no events would be delivered to you.

Please note that this is a pretty recent version of Gerrit which differs in a few ways from the version used by e.g. the Qt project. Most of the changes are in the UI, e.g. to apply stuff locally, use the Download menu at the top-right corner of the change view.

Advanced: Using gpush

Gerrit works well out-of-the-box with regular git functionality, but for some advanced usage, you might want to use script by Qt's developers -- gpush. It provides smart interface to some Gerrit features. You can get it along with qtrepotools from official Qt repository. Just make sure that its bin directory is in $PATH. Here are some examples of its usage:

 # Pushes HEAD:refs/for/branch to 'gerrit' without any reviewers
 git gpush
 # Pushes HEAD:refs/for/$TRB to 'gerrit', adding mariuso as a reviewer
 # and sends thiago a CC mail
 git gpush +mariuso =thiago
 # Pushes HEAD:refs/for/buildsystem to 'gerrit', no reviewers
 git gpush :refs/for/buildsystem

Nice Tweaks

Getting Information About Review through Git

Once a change is approved and submitted to git, Gerrit automatically inserts a proper note about that into git. Here's how to enable showing of them. At first, configure git so that it gets fetched automatically (assuming origin is your KDE remote, and that at least one change has been already merged:

 git config --add remote.origin.fetch refs/notes/review:refs/notes/review
 git fetch origin

To show this information, add a fancy argument to e.g. git log:

 $ git log --notes=review
 commit 39f98861cec1cba192171b6ad998328b16106c46
 Author: Jan Kundrát <[email protected]>
 Date:   Sat Sep 6 17:30:57 2014 +0200
 
 tests: Improve debugging for extra unexpected child tasks
   
 I can as well just leave this in instead of removing it every time I hit a
 failure in the subsequent QVERIFY.
   
 Change-Id: Ia4a7c72d0193827e013bfe3d47a0bd7a99567058
 
 Notes (review):
   Code-Review+2: Jan Kundrát <[email protected]>
   Submitted-by: Jan Kundrát <[email protected]>
   Submitted-at: Mon, 08 Sep 2014 09:19:44 +0200
   Reviewed-on: https://gerrit.vesnicky.cesnet.cz/r/11
   Project: trojita
   Branch: refs/heads/master

Doing Pushes the Fancy Way

If you dislike the refs/for/ prefix, you can set up gerrit so that you can push "directly to branch", yet git will do the right thing for you:

 git config remote.gerrit.push refs/heads/*:refs/for/*
 git push gerrit

Specifying reviewers when pushing

You can also add reviewers while you submit stuff for review. To add three people, [email protected], [email protected] and [email protected], do it like this:

 git push gerrit HEAD:refs/for/master%[email protected],[email protected],[email protected]

At these points you can clearly see advantages of git gpush script, because it's more user friendly and supports nicknames along with emails as well.

Anything Else?

As Gerrit is based on git, there is a ton of possible workflows. Maybe we should settle on one and thoroughly document it?

What tricks do you find neat?

Sysadmin Stuff

Adding Projects

The name of the project repository at KDE's git and in gerrit have to match. One can only add regular project repositories, not personal clones or scratch repos.

At first, set up KDE's infrastructure so that any pushes propagate to Gerrit:

 cd kde/repo-management
 # do an equivalent of commit 6bd604f73902d9a14c05a2abb88da5e1838ce2ea
 echo ssh://[email protected]:29418/YourRepoName \
   > repo-configs/remote-update/YourRepoName.git
 git commit -a
 git push

Now setup the project in Gerrit:

 ssh -p 29418 gerrit.vesnicky.cesnet.cz gerrit create-project \
   --parent sysadmin/gerrit-kde-traditional-projects NameOfGitRepo

This creates a refs/meta/config branch within Gerrit's git copy, which gets pushed to git.kde.org, which in turn notices that it should push missing branches to Gerrit, and stuff just works from that time on.

How Stuff Works

Everything was deployed to CESNET's cluster within the XIFI project. The VM runs within OpenStack, and everything is deployed by Puppet. Ask jkt for details, full release is pending.

TODO list

  • Documentation: Write a howto for users/developers (this page)
  • Define how to get support
    • through IRC at #kde-sysadmin on freenode (ping jkt)
    • sysadmin's tickets?
      • gerrit admins have to be able to read these
    • Anything which needs hard-core stuff like recreating the whole VM: a sysadmin should file a ticket at CESNET's XIFI support. Any user who does that will be shot.
  • give access to additional admins
    • Frederik Gladhorn -- done
    • Ben Cooksley -- done
    • vblazquez -- done
    • tosky?
    • Who else? Register at Gerrit, send a mail to jkt and I'll make it happen.
  • Improve the CI
    • Tool idea: run krazy over submitted patches before committing and inform committer about possible changes
  • Get SSH keys from LDAP (bugreport)

This page was last edited on 22 September 2017, at 16:19. Content is available under Creative Commons License SA 4.0 unless otherwise noted.