Setting up your environment
Creating an SSH Alias
Since access to gerrit.asterisk.org is likely to occur often if yo're submitting patches, you may want to set up an SSH alias:
This will allow you to access the repository as shown below:
You can skip this step if you're only downloading patches for testing.
Most Gerrit users will be submitting patches for review and will need the
git review command. It's not normally installed by default when you install git so it must be installed separately. The package is called
git-review and should be available via most package managers. If not, you can install it using pip:
You can skip this step if you're only downloading patches for testing.
In every repository you plan on submitting patches from, you'll need to set your email to match that expected by Gerrit. You can set it in each repository after you've cloned it or you can set it globally.
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, clone it from the Official Asterisk GitHub Mirror
Clone the repository:
You can also clone and check out a branch in one step
To push reviews to Gerrit, you'll need the commit hook that generates the Gerrit Change-Id and appends it to every commit message. You can install the hook easily with git review.
It's imperative that once a Change-Id is added to a review it's not changed. Gerrit uses it to associate multiple commits with a single review and associate cherry-picks among branches.
Gerrit Review Submit Workflow
Now that the repository is set up, it's time to do some real work! Let's say you have a change you wish to make against the Asterisk 13 branch.
Get an Asterisk Issue ID
There should be an Asterisk issue open for every change you submit. If you don't have one already, create a new issue at https://issues.asterisk.org. Let's say you're using ASTERISK-12345.
Create a working branch in your repository
You'll want to keep the local branches that track remote branches, like 13, 14, master, in a pristine condition so create a new working branch that's based on the remote branch you're making the change against. Using the Asterisk issue id as the branch name will make things easier later on. You should always start your change in the oldest branch to which the change will apply which is 13 in this example.
Do Some Work!
Test Your Work!
When you submit your review, it will automatically be built and the Asterisk unit tests run so to save re-work time, you should run the Asterisk unit tests against your changes before you submit. To do so, configure asterisk with the
--enable-dev-modeflag and enable
TEST_FRAMEWORKin menuselect. After installing Asterisk in your test environment (and you should have a test environment), you can run the tests from the Asterisk CLI with the
test execute allcommand.
If you have the Asterisk Testsuite installed, running the test suite is also recommended since it will be run against your change before the change is merged. See Installing the Asterisk Test Suite for more information.
You have to commit before you submit and the commit message is crucial. For more information about commit messages, see Commit Messages. You'll notice that when you edit the commit message, you'll see that the Gerrit Change-Id was automatically added to the end. DON'T ALTER OR REMOVE IT!! You'll see why this is important later.
Here's a quick sample commit message:
Submitting is easy:
13represents the branch you're submitting this patch against. The default is
masterso don't forget to specify it.
If the submit is successful, you'll see a confirmation that looks like so:
9999is the review number.
If you're making your change to the Asterisk 13 or 14 branches, you'll probably need to cherry-pick your change to other branches. For changes to 13, cherry-pick to 14 and master. For changes to 14, cherry-pick to master. The easiest way to do this is via the Gerrit web user interface.
Log into Gerrit at http://https://gerrit.asterisk.org and open your change. Notice that the change topic is set to ASTERISK-12345. This was automatically set because the name of the working branch you submitted from was ASTERISK-12345. If it's not set correctly to the Asterisk issue id, set it now. If you don't use the Asterisk issue id as the working branch name, you can set the topic when you submit using the
git reviewas follows:
git review -t ASTERISK-1234513
- Whenever possible, you should cherry pick from the oldest branch to the newest in order. Click the Cherry Pick button and choose the destination branch. Assuming the change was originally submitted against 13, choose 14 and click the Cherry Pick Change button. Gerrit will create a new review for you against the destination branch. Notice though that Gerrit altered the Topic by appending the destination branch. You'll need to reset it to just the Asterisk issue id. Once that's done, click Cherry Pick again and repeat the process for the master branch.
- Watch for verification
As each review is created, Gerrit will automatically schedule a verification step with Jenkins (our continuous integration platform). To pass the verification, Asterisk has to build successfully with your change and all unit tests must pass. Passing is usually the signal to reviewers that it's a valid patch and they can spend time reviewing it. If it fails, it's up to you to examine the results by following the links that Jenkins added to the comments and taking appropriate action.
- Respond to comments
The worst thing you can do is push a review then not respond to comments!. This tells reviewers that the review isn't important to you and the review will probably keep falling further back in the queue.
- Next Steps
If your review is accepted without the need for re-work, you need to nothing further. Otherwise, read on.
Updating a Review (documentation update in progress)
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:
Re-push the changes:
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.
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.
If you have already submitted a patch for review, you may cherry pick to a new branch using
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:
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.
The repositories on Gerrit typically require all changes in all of the mainline branches to be reviewed prior to merging. While this is appropriate for the mainline branches, sometimes, it is useful to have a branch on the central server that multiple developers can use for collaboration. These branches exist within a special branch namespace,
team. Registered Gerrit users have the ability to manipulate branches within that namespace directly, bypassing the usual Gerrit code review process.
Team Branch Manipulation in Gerrit
Creating a new Team Branch
Creating a new team branch can be done at any time from a local branch. For example, to create a new team branch from local
Check out a Team Branch
Checking out a team branch is done in the same way as a mainline branch:
Pushing to a Team Branch
Pushing to a team branch can be done directly. This bypasses Gerrit's peer review. Note that team branches can be peer reviewed if desired, using the same mechanism as a 'normal' Gerrit peer review.
Delete a Team Branch
Deleting a team branch is done by pushing an empty local branch (nothing) to the team branch. Note that you have to use
git push --force.
Recovering a Subversion Team Branch
While the Subversion Team branches were moved over to Git with their entire history, much of that history typically consists of Automerge commits. These commits are not well understood by Git; from Git's perspective, they are completely independent from the mainline commits they merged over. This can cause a "standard" rebase to fail miserably: the rebase will not realize that the Automerge commits are identical to those on the branch being rebased to. As a result, you'll often have a lot of merge conflicts if you attempt to rebase directly.
While working through the merge conflicts in a rebase is an option, an easier approach may be to simply re-build the branch on the current state of the mainline branch it wants to track. This example walks through that process, performing a rebase of branch
team/mjordan/trunk-http-stuff-and-things on top of
Checkout the subversion team history branch into a temporary local branch:
- Determine the useful commits to pull over. In this case, we're going to skip:
- All commits from
- All commits that modify Subversion properties or create Subversion branches.
In the above screenshot, we want the three commits from
Matthew Jordanbetween the
automerge canceland the
Matthew Jordan: Re-enable automerge.
- Record the hashes of the commits you want to carry-over.
- All commits from
Checkout a new branch for your work, tracking whatever canonical mainstream branch is appropriate:
Cherry-pick each commit over, solving merge conflicts as necessary:
If desired, fix up any history:
Remove the temporary branch:
Push the branch up to your team branch location:
Problem: attempting to run
git review results in something like the following:
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:
Problem: Unable to login to gerrit.asterisk.org
Solution: Until your Contributor License Agreement is approved, you will not be able to sign into the project OpenID provider or Gerrit. See the "Creating an Account" section for instructions on how to resolve this.
Problem: Unable to unsubscribe from Gerrit notifications
Solution: You may have mistaken the Gerrit notifications on a mailing list for notifications associated with your account. Of course if the notifications are being received via a mailing list then you would need to unsubscribe from the entire mailing list to stop receiving related mailings.
Other possibilities are that you have multiple accounts or are receiving notifications via forwarding from another E-mail address.