Setting up your Gerrit Account

Upon logging in for the first time, you will need to perform the following:

1. Set your username for your account. This can be any username, although we highly recommend matching your Atlassian username. To set your username:
   1. Click on your name in the top-right corner.
   2. Click "Settings"
   3. Click "Profile" on the left side of the screen.
   4. In the top text box in the center, enter your user name, and confirm.
2. Add your SSH public key.

Cloning from Gerrit

While access to the underlying git repository is open to anyone via anonymous HTTP access, this guide will assume that you want to push changes up as well. For that, Gerrit uses SSH. If you are only looking to obtain the source code for a particular repository, you may just use the HTTP methods shown below.

1. Clone the repository:
   

   1. SSH:

   2. HTTP:

   3. Anonymous HTTP:

2. Copy the commit-msg hook into your local .git/hooks folder:

   1. If you have git-review installed:

   2. Otherwise:

      The commit-msg hook adds the Change-Id automatically to git commit messages. A Change-Id is necessary for Gerrit to associate multiple patch sets together. For more information, see Change-Ids.

Creating an SSH Alias

Since access to gerrit.asterisk.org is likely to occur often, you may want to set up an SSH alias:

This will allow you to access the repository as shown below:

Pushing to Gerrit for Code Review

Use git review

1. Install git-review:

2. To submit a change to master as a draft:

3. To submit a change to master:

   Note that this will automatically publish the change to the asterisk-dev mailing list!
   
   

4. To submit a change for a particular branch:

5. To submit a change, including the ASTERISK issue:

Use git push

Pushing to Gerrit for code review can always be done using standard git commands. This is done by pushing to the refs/for/[branch]. Generally, this will be master, unless pushing to a particular mainline Asterisk branch.

Updating a Review

1. Reviews are automatically updated so long as commits contain the same Change ID. If your review has any findings, rebase the commits as appropriate, making sure the Change ID is preserved:

2. Re-push the changes:

   or:

Branch Cherry-Picking

Patches being submitted to the project must be cherry-picked to other branches when either:

• The patch is a bug fix. In this case, the patch should be cherry-picked to all supported branches that have the bug.

• The patch is a new feature or improvement, and tests have been written to cover the new feature or improvement. In that case, the patch may be submitted to other supported branches.

  Icon

  Not all changes are appropriate for all branches. See Software Configuration Management Policies for more information. If you have questions about whether or not a change is appropriate for a particular branch, feel free to ask on the asterisk-dev mailing list or in #asterisk-dev.

Cherry-picking can be done either when a patch is first proposed, or it may be done when the patch has been reviewed but prior to it being submitted. If you plan on cherry-picking after an initial review, please indicate so in a comment on the review.

Cherry-Picking in Gerrit

If your patch applies cleanly to a branch, you can cherry-pick directly in Gerrit. On your review, select the Cherry-Pick button:

In the resulting dialog, enter the branch you want to cherry-pick to, then select Cherry Pick Change.

If the change merges cleanly, a new review will be opened with your cherry-picked change. If the change could not be merged, and error will appear and you will need to use one of the manual methods listed below.

Cherry-Picking using git review

If you have already submitted a patch for review, you may cherry pick to a new branch using git review:

As an example, if we previously posted for review a code change for Asterisk 11, and the Gerrit Review ID is 30, we might use the following for Asterisk 13:

Cherry-Picking using git cherry-pick

You may cherry pick using git cherry-pick as well. When performing the cherry-pick using git, make sure that the Change-Id header is the same between all branches.

As an example, if we committed the following to Asterisk 13:

We could then cherry pick this back to Asterisk 11 using the following:

The resulting commit must have the same Change-Id as the Asterisk 13 commit for Gerrit to recognize that this is a cherry-picked commit:

When posting it for review to Gerrit, you should also use the same topic as the original patch. Generally, this is the ASTERISK issue.

Troubleshooting

git-review

Problem: attempting to run git review results in something like the following:

Traceback (most recent call last):
  File "/usr/local/bin/git-review", line 11, in <module>
    sys.exit(main())
  File "/usr/local/lib/python2.6/dist-packages/git_review/cmd.py", line 1132, in main
    (os.path.split(sys.argv[0])[-1], get_version()))
  File "/usr/local/lib/python2.6/dist-packages/git_review/cmd.py", line 180, in get_version
    provider = pkg_resources.get_provider(requirement)
  File "/usr/lib/python2.6/dist-packages/pkg_resources.py", line 176, in get_provider
    return working_set.find(moduleOrReq) or require(str(moduleOrReq))[0]
  File "/usr/lib/python2.6/dist-packages/pkg_resources.py", line 648, in require
    needed = self.resolve(parse_requirements(requirements))
  File "/usr/lib/python2.6/dist-packages/pkg_resources.py", line 546, in resolve
    raise DistributionNotFound(req)
pkg_resources.DistributionNotFound: git-review

Solution: Run

sudo pip install --upgrade setuptools

on your command line

Problem: attempting to run git review results in "unpack failed: error Missing tree":

Description:  There is an incompatibility between certain version of git and gerrit that causes this error when the commit to be pushed was amended and only the commit message changed.
Solution:  Run git push manually with the --no-thin option:

git push --no-thin asterisk:{repo} HEAD:refs/for/master