Cellular Network Infrastructure

h1. Contributing using Gerrit

{{>toc}}

At [[OpenBSC:OsmoDevCon2016]] we discussed problems with our past contribution / patch submission process using mails on the mailing list as well as patchwork.  The result is that we want to give Gerrit a try for some time and see if it helps us to have a better process

Gerrit is a review tool that integrates nicely with git and ssh. You can find general information about Gerrit at https://www.gerritcodereview.com/

The advantages of Gerrit are:

* patch submission status is automatically tracked, also with several revisions for a patch set.

* patches are build-tested (and possibly even further tested) by jenkins before they are applied

* developers + maintainers can formally vote on a patch (developer: -1/0/+1, maintainer: -2/0/+2)

* once a patch has +2 score, it can be (automatically) merged into master

* patch sumissions not via git send-email but direcly from git

h2. Osmocom Subprojects using Gerrit

The following projects use Gerrit to contribute changes:

* libosmocore.git

* libosmo-abis.git

* libosmo-netif.git

* libosmo-sccp.git

* libsmpp34.git

* openbsc.git

* osmo-bts.git

* osmo-iuh.git

* osmo-pcu.git

* cellmgr-ng.git

* osmo-sip-connector.git

h2. Configuring Gerrit/Account

You will need to sign-up at https://gerrit.osmocom.org/login/. If you have an Osmocom Redmine account you can use https://osmocom.org/openid as OpenID provider. If you have no Osmocom redmine account, you can simply create one online at the "Register" link in the upper right corner.

Even without an existing or new redmine account, you should also be able to use any other OpenID provider to authenticate against gerrit (untested).

After the initial sign-up you will need to:

* Pick a username (can not be changed)

* Add your public ssh key(s)

* Add email addresses you intend to use as author/comitter

h2. Setting up Gerrit for commits and pushing

* Add the remote to be able to fetch and push to gerrit

* Fetch the commit hook that adds Change-Id to each commit to uniquely identify a commit

<pre>

USERNAME=gerrit_user_name

PROJECT=$(basename $PWD)

git remote add gerrit ssh://$USERNAME@gerrit.osmocom.org:29418/$PROJECT.git

scp -P 29418 $USERNAME@gerrit.osmocom.org:hooks/commit-msg .git/hooks/

</pre>

* In case your local username matches the gerrit username, the setup shortens to

<pre>

PROJECT=$(basename $PWD)

git remote add gerrit ssh://gerrit.osmocom.org:29418/$PROJECT.git

scp -P 29418 gerrit.osmocom.org:hooks/commit-msg .git/hooks/

</pre>

Then

* Push for review

<pre>

git push gerrit HEAD:refs/for/master

</pre>

* Push a user branch

<pre>

git push gerrit HEAD:refs/heads/users/$USERNAME/topic

</pre>

* Directly push to master if you are allowed to

<pre>

git push gerrit HEAD:refs/heads/master

</pre>

* List changesets in gerrit

<pre>

git ls-remote gerrit changes/*

</pre>

h2. Tips and Tricks

If you need to adjust and re-submit patches the easiest way is to create throw-away branch ("R D" in magit-gerrit in emacs for example), make you changes/amendments and than send patch(es) back to gerrit while removing temporary branch automatically with "git review -f".