Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: tighten up code block whitespace

Overview

The Asterisk project uses Gerrit for code reviews, continuous integration validation, and git management. When creating a patch to Asterisk or its various related projects, all patches should be pushed to Gerrit for review.

Use of Gerrit is beyond the scope of this wiki page - for in depth information, see the Gerrit documentation.

 

SSH Host Key Fingerprint

Gerrit uses an internal ssh server on port 29418 for all git operations.  This is the current host key fingerprint,

Code Block
As of 2021-08-26, the ssh host key fingerprint for gerrit.asterisk.org port 29418 is:
2048 SHA256:fVUWWssynxRxCRZWmHVWoQAqwYC4pODCwoRrMOqM3QM [gerrit.asterisk.org]:29418 (RSA) 

More instructions for using ssh are below.

 

Creating an Account

Gerrit uses OpenID in conjunction with the Asterisk project's Atlassian infrastructure to provide single sign-on. If you already have an account in the Asterisk project infrastructure (such as JIRA) and have signed a Contributor License Agreement, you should be able to sign in to Gerrit automatically.

  1. Create an account at signup.asterisk.org.

  2. Sign a Contributor License Agreement.

    Warning

    Until your Contributor License Agreement is approved, you will not be able to sign into the project OpenID provider or Gerrit.

  3. Browse to Gerrit, and click Sign In.

  4. This will redirect to openid.asterisk.org. Sign in with your Atlassian username/password.

  5. Upon signing in successfully, you will need to authorize Gerrit to access your OpenID. When you have done so, you should be redirected back to Gerrit, and will be signed in.

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.

      Warning

      Failure to set your username will result in clones using SSH failing, despite adding your SSH key. If you can not clone using SSH please ensure you have set your username.

  2. Add your SSH public key.
Panel
titleOn This Page

Table of Contents
maxLevel2

 

 

 

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:

      Code Block
      $ git clone ssh://{user}@gerrit.asterisk.org:29418/{repo}
    2. HTTP:

      Code Block
      $ git clone https://{user}@gerrit.asterisk.org/{repo}
    3. Anonymous HTTP:

      Code Block
      $ git clone http://gerrit.asterisk.org/{repo}
  2. You can clone a specific repo branch only:
    1. Cloning Asterisk branch 13 via HTTP to the "asterisk-13" folder:

      Code Block
      git clone -b 13 http://gerrit.asterisk.org/asterisk asterisk-13
  3. Copy the commit-msg hook into your local .git/hooks folder:

    1. If you have git-review installed:

      Code Block
      $ git review -s
    2. Otherwise:

      Code Block
      $ scp -p -P 29418 {user}@gerrit.asterisk.org:hooks/commit-msg {local-repo}/.git/hooks/

      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.

Setting up your environment

Creating an SSH Alias

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

Code Block
$ cat ~/.ssh/config
...
Host asterisk
  Hostname gerrit.asterisk.org
  Port 29418
  User {user}

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

Code Block
$ git clone asterisk:{repo}

Pushing to Gerrit for Code Review

There are multiple ways to push changes to Gerrit for code review, the easiest of which is to use git review. When committing changes, be sure to follow the Commit Messages guide.

Anchorgit-reviewgit-reviewUse git review

Install git-review:

Code Block

Install git-review

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: 

Code Block
titleInstall git-review from git
languagebash
$ pip install git-review
  • To submit a change to master as a draft:

    Code Block
    $ git review -D
  • To submit a change to master:

    Code Block
    $ git review

    Note that this will automatically publish the change tothe asterisk-code-review mailing list!

  • To submit a change for a particular branch:

    Code Block
    $ git review {branchname}
  • To submit a change, including the ASTERISK issue if there is one as the topic for the review:

    Code Block
    $ git review -t ASTERISK-12345
  • Use git push

    Note
    titleUse git review

    While you can always use git push instead of git review, using git review is highly recommended. It was designed for use with Gerrit, and makes your life much easier.

    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.

    Code Block
    $ git push asterisk:{repo} HEAD:refs/for/master

    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:

      Code Block
      $ git rebase -i
    2. Re-push the changes:

      Code Block
      $ git review

      or:

      Code Block
      $ git push asterisk:{repo} HEAD:refs/for/master

    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.

      Note

      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:

    Image Removed

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

    Image Removed

    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:

    Code Block
    $ git review --cherrypick {review id} {origin branch}

    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:

    Code Block
    $ git review --cherrypick 30 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:

    Code Block
    commit dc8f87145c352c1bcf1a3361802aac26da5f50e2
    Refs: review/asteriskteam/file-version-13, file-version-13
    Author:     Asterisk Development Team <[email protected]>
    AuthorDate: Sun Apr 12 12:59:22 2015 -0500
    Commit:     Asterisk Development Team <[email protected]>
    CommitDate: Sun Apr 12 20:20:19 2015 -0500
    
        git migration: Remove support for file versions
    
        Git does not support the ability to replace a token with a version
        string during check-in. While it does have support for replacing a
        token on clone, this is somewhat sub-optimal: the token is replaced
        with the object hash, which is not particularly easy for human
        consumption. What's more, in practice, the source file version was often
        not terribly useful. Generally, when triaging bugs, the overall version
        of Asterisk is far more useful than an individual SVN version of a file.
        As a result, this patch removes Asterisk's support for showing source file
        versions.
    
    	ASTERISK-12345
    
        Change-Id: Ia932d3c64cd18a14a3c894109baa657ec0a85d28

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

    Code Block
    $ git cherry-pick dc8f87145c352c1bcf1a3361802aac26da5f50e2

    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:

    Code Block
        Change-Id: Ia932d3c64cd18a14a3c894109baa657ec0a85d28

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

    Code Block
    $ git review -t ASTERISK-12345 11

    Team Branches

    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.

    Note
    titlePosting For Peer Review

    When a code change in a team branch is ready for peer review, using the git review tool or pushing the change to Gerrit's refs/for/[branch] will still automatically post it for review on Gerrit. The instructions on this page assume that developers wanting to use team branches want to perform some development collaboratively without posting the change for review.

    For instruction on posting a change for review, see Pushing to Gerrit for Code Review.

    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 master:

    Code Block
    $ git push origin master:refs/heads/team/mjordan/awesome-feature

     Check out a Team Branch

    Checking out a team branch is done in the same way as a mainline branch:

    Code Block
    $ git checkout -b awesome-feature -t origin/team/mjordan/awesome-feature

    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.

    Code Block
    $ git push origin HEAD:refs/heads/team/mjordan/awesome-feature

    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.

    Code Block
    $ git push --force origin :refs/heads/team/mjordan/awesome-feature
    Warning

    It should go without saying, but be careful when deleting a team branch. All registered users have access rights to the team area - as such, anyone can affect someone else's team branch.

    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 master.

    1. Checkout the subversion team history branch into a temporary local branch:

      Code Block
      $ git checkout -b http-caching-temp -t origin/team/mjordan/trunk-http-stuff-and-things
    2. Determine the useful commits to pull over. In this case, we're going to skip:
      1. All commits from Automerge script.
      2. All commits that modify Subversion properties or create Subversion branches.
        Image Removed
        In the above screenshot, we want the three commits from Matthew Jordan between the Automerge: script automerge cancel and the Matthew Jordan: Re-enable automerge.
      3. Record the hashes of the commits you want to carry-over.
    3. Checkout a new branch for your work, tracking whatever canonical mainstream branch is appropriate:

      Code Block
      $ git checkout -b http-caching -t origin/master
    4. Cherry-pick each commit over, solving merge conflicts as necessary:

      Code Block
      $ git cherry-pick 5037821233a366f4afae83c732eb318e64bdb6f5
      $ git cherry-pick 9905eaad7a8c8a13363ae4129d7d483c8559cb7a
      $ git cherry-pick 32fe36b0e14f8c072c2bfea9443a946cfe3628d6
      $ git cherry-pick a5eb0d4b178eee070047549d635ada8d562c3d73
    5. If desired, fix up any history:

      Code Block
      $ git rebase -i
    6. Remove the temporary branch:

      Code Block
      $ git branch -d 
      Tip

      You may get the following warning:

      Code Block
      warning: deleting branch 'http-caching-temp' that has been merged to
               'refs/remotes/origin/team/mjordan/trunk-http-stuff-and-things', but not yet merged to HEAD.
      Deleted branch http-caching-temp (was 9c6910d).

      That's okay. You don't want to merge the whole thing to HEAD, as the Automerge script commits are duplicates of commits already in HEAD.

    7. Push the branch up to your team branch location:

      Code Block
      $ git push origin HEAD:refs/heads/team/mjordan/http-caching
      Tip

      In this example, a new team branch is being made - team/mjordan/http-caching. This way, if something is missed in the cherry-picks, I haven't blown away my Subversion branch.

    Troubleshooting

    git-review

    Note
    It is recommended that you have git-review version 1.27.0 installed. You can check the installed version using "git review --version". If it is an old version you can install it using pip to receive the latest one.

     

    Prepare git

    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.

    Code Block
    titleSet per repository
    languagetext
    $ cd <repository>
    $ git config --local --add user.email <your email>
    $ git config --local --add user.name <your full name>
    Code Block
    titleSet globally
    languagetext
    $ git config --global --add user.email <your email>
    $ git config --global --add user.name <your full name>

    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:

    Code Block
    titleClone using full SSH URL
    languagetext
    $ git clone ssh://{user}@gerrit.asterisk.org:29418/{repo}

    or

    Code Block
    titleClone using SSH alias
    languagetext
    $ git clone ssh://asterisk/{repo}

    You can also clone and check out a branch in one step

    Code Block
    titleClone asterisk and check out branch 13
    languagetext
    $ git clone -b 13 ssh://asterisk/asterisk asterisk-13

    If you're only retrieving patches and don't need to submit, you can clone from https:

    Code Block
    titleClone using Anonymouns HTTPS
    languagetext
    $ git clone https://gerrit.asterisk.org/asterisk

    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.

    Code Block
    titleInstall the Gerrit commit hook
    languagetext
    $ git review -s

    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 and 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.

    Code Block
    $ git checkout 13
    $ git checkout -b ASTERISK-12345

    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-mode flag and enable TEST_FRAMEWORK in 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 all command.  

    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.

    Commit

    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:

    Code Block
    res_pjsip:  Change something in res_pjsip
     
    This is where you should describe the change and any background information
    that will help a reviewer or future developer understand the purpose of
    the change.
     
    ASTERISK-12345 #close
    Reported-by: Someone other than you
     
    Change-Id: I6dca12979f482ffb0450aaf58db0fe0f6d2e389
     

    Submit

    Submitting is easy:

    Code Block
    titleSubmit a patch for review
    languagetext
    $ git review 13 

    13 represents the branch you're submitting this patch against.  The default is master so don't forget to specify it.  

    If the submit is successful, you'll see a confirmation that looks like so:

    Code Block
    remote: Processing changes: new: 1, refs: 1, done            
    remote: 
    remote: New Changes:        
    remote:   http://gerrit.asterisk.org/r/9999 new review        
    remote: 
    To ssh://gerrit.asterisk.org:29418/asterisk
     * [new branch]      HEAD -> refs/publish/13/9999
    
    

    9999 is the review number.

    Cherry Pick

    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.

    1. Log into Gerrit at 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 -t option to git review as follows: git review -t ASTERISK-12345 13

    2. 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.  You'll get new review numbers for each cherry-pick of course.

    You can cherry-pick a review from the command line if you so wish:

    Code Block
    titleCherry pick a review from the command line
    $ git review --cherrypick 9999 14 

    This will cherry pick review 9999 to the 14 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

    Making updates to a review is a bit tricky because you don't want to create new commits or new reviews with each update.  Here are the steps:

    Pull down the current review

    Code Block
    $ git review -d 9999

    This will create (or reuse) a branch named "review/<your_name>/<topic>" and switch you to it.  In this example and assuming your name is "Joe Developer", the branch would be "review/joe_developer/ASTERISK-12345".

    Make and test your changes

    If you wind up adding a file, don't forget to do a git add <filename> on the new file.

    Amend the original commit

    Code Block
    titleAmend a commit
     $ git commit -a --amend

    It is CRITICAL that you amend your original commit and not create a new commit.  Failing to amend will generate a new Change-Id and will cause Gerrit to create a NEW review instead of creating a new patchset on the existing review.

    Re-submit

    Code Block
    $ git review 13

    Don't forget the base branch.

    Cherry Pick

    As with the initial submit, cherry-pick to the other applicable branches. 

    If you have to make multiple changes over the lifetime of the review, you should always download the same review, 9999 in this case.  This is because the branch name that gets generated for the review doesn't include the base branch.  In our example, let's say you got review 10000 when you cherry-picked 9999 to the 14 branch.  If you do git review -d 9999 then later do git review -d 10000, you'll get a warning from git that the base branches aren't the same.  If this happens, check out another branch temporarily, delete the review branch, then download the review again.

    Code Block
    $ git checkout 13
    $ git branch -D reviews/joe_developer/ASTERISK-12345
    $ git review -d 10000

    Advanced Topics

    What do do when a cherry-pick fails, etc.  Coming Soon!

     

    Troubleshooting

    git-review

    Problem: attempting to run git review -s fails to find gerrit.

    Solution: You may need to add an explicit git remote named "gerrit".

    No Format
    git remote add gerrit <ssh-url-to-the-gerrit-repo>

    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: attempting to run git review results in something like the following:

    No Format
    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

    No Format
    $ 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:

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

    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.