Skip to end of metadata
Go to start of metadata

Info

  • NEVER embed jar, war, tar, gz, gzip, zip in Gerrit

Overview

Gerrit is an Open Source web-based collaborative Code Review tool that integrates with Git.
For all ONAP projects, Gerrit is available at https://gerrit.onap.org and documentation at https://gerrit.onap.org/r/Documentation/index.html 
Gerrit offers an extensive search capability by using a query syntax documented at https://gerrit.onap.org/r/Documentation/user-search.html 
To get started, you can watch this 14 minutes video that was done for OPNFV project.

To understand deeper Gerrit UI, this is a good source of info https://gerrit-review.googlesource.com/Documentation/user-review-ui.html 
Log into Gerrit using your Linux Foundation ID (LFID).

Anyone who has a valid Linux Foundation ID can submit code as a contributor. You simply need to login into Gerrit using your Linux Foundation ID.
The committer role requires specific permissions per project setup by Linux Foundation. Do not contact directly Linux Foundation's Help Desk to ask for Committer privileges but rather work with the Release Manager who will make it happen through the TSC.

Project committers group are setup in the form of onap-gerrit-${PROJECT}-committers. Connect to https://identity.linuxfoundation.org to see which group you are part of.
Committers are nominated according to Configuring Gerrit.

Tools

Whatever OS your are using (Mac, Linux, PC) the following tools must be installed and configured:

  1. git client : to perform all the Git task (clone, pull, branch, checkout,...) 
  2. git-review : to submit your code into Gerrit
  3. SSH client : to connect securely to Gerrit server

SSH

Most users use SSH to authenticate with remote servers. To perform such authentication with Gerrit, your have to provide your SSH Public key to Gerrit (User Account->Settings->SSH Public keys).
In case you can't use SSH (because network do not allow SSH on port 29418), you can use HTTPS.

HTTP Workaround for Gerrit inside a Corporate firewall/proxy blocking SSH

A couple of other things specific to Gerrit

  • Gerrit does not allow you push directly to your branch. If you're not using the git-review plugin then to push a change against your branch it will be as follows:
Pushing Code into Gerrit
# in this case
BRANCH=master
git push origin HEAD:refs/for/$BRANCH
  • Your change will go to Gerrit to be reviewed. It will not be merged onto the branch until someone with committer rights gives it a Code-Review +2. Normally there are verification jobs setup in Jenkins that would vote on the Verified field, but as your project(s) don't just yet (oparent being the exception as they pushed a verify job this afternoon) a committer will also have to flag Verified +1. Once both fields are at max value, then a committer will have the ability to Submit the code. It will not be merged until the final Submit has occurred.

Once the code is submitted, Gerrit moves the code from the Open tab https://gerrit.onap.org/r/#/q/status:open to the Merged tabs https://gerrit.onap.org/r/#/q/status:merged.

  • Your code import cannot be a historical import. That is, you can't be bringing history from an external SCM tool into a Gerrit repo under Linux Foundation control. This is a policy Linux Foundation had in place for a very long time and is non-negotiable. This means your import will be a squash commit of any code coming in.

HTTP Sequence of events

In this case you need to have Gerrit generating a password for you (User Account->Settings->HTTPS Password->Generate Password).

Clone using https syntax
export LFID=<YOUR_LFID_HERE>
export REPO=common-services-external-system-registration

git clone https://${LFID}@gerrit.onap.org/r/a/${REPO}.git

cd ${REPO}
# acquire the commit hook
curl -Lo ./.git/hooks/commit-msg https://gerrit.onap.org/r/tools/hooks/commit-msg
chmod +x ./.git/hooks/commit-msg
# create your code commit
cp ${codeblob} ./
git add .
git commit -asm 'Initial code import'
git push origin HEAD:refs/for/master

A couple of things to note here:

The URL will be /r/a/${REPO}.git (the .git is optional) /r == the web url that Gerrit lives on. 
/a == authenticated https. 
Without /a it will try to do an anonymous http connection and it will fail for pushes, at least when we open the repos to public access.

The commit has a -s which gives you the 'Signed-off-by: Name <email>' footer in your commit message. Your 'Name <email>' portion must match what Gerrit has registered. And it's case sensitive. (Commit message example)

If you do not have the Gerrit commit hook installed you'll get an error when you push telling you how to get it. Once you've obtained it you'll want to run the following operation before trying to push again:

Amending commits
git commit --amend

Just resave your commit message. After you do that if you do a 'git log' you should notice that a 'Change-Id:' line was added above your 'Signed-off-by' footer. This Change-Id is required by Gerrit.

SSH Sequence of events

Clone using ssh syntax
export LFID=<YOUR_LFID_HERE>
export REPO=common-services-external-system-registration

git clone ssh://${LFID}@gerrit.onap.org:29418/${REPO}.git

cd ${REPO}
# acquire the commit hook
curl -Lo .git/hooks/commit-msg https://gerrit.onap.org/r/tools/hooks/commit-msg
chmod +x .git/hooks/commit-msg
# creat your code commit
cp ${codeblob} ./
git add .
git commit -asm 'Initial code import'
git push origin HEAD:refs/for/master

You'll note that this is essentially the same. The primary difference is that you won't be getting prompted for a password as it only operates with SSH keys. 

Speaking of passwords. The HTTPS method does not use your LFID password, you need to have Gerrit generate one for you: Login -> select your name in the right corner -> Settings -> HTTP Password -> Generate Password

Committer

In order to avoid delays merging the code, it is expected that committers or contributors review the code within the next 36 business hours after the contributor/committer has submitted his code.
There are 2 ways for a Committer/contributor to be notified by email on the code to review:

  1. the contributor/committer specifically enters the committer/contributor name in the submission form.
  2. any contributor/committer add their self to the list in gerrit
  3. the contributor updates his Gerrit's settings to Watch his projects.

Things to keep in your radar

Merge Conflict


It may happen that you cannot merge into the upper branch. Gerrit will render this behavior by indicating in the Status column the message Merge Conflict.
You can also run the following query to display all the submissions in status Merge Conflict.

To address the Merge Conflict issue 3 solution scenarios are possible:

  1. A change that has already been merged is in conflict with the current change, try to rebase the change by clicking the "Rebase" button in Gerrit UI. 
  2. A simple rebase can't fix the problem because it is fundamentally unsolvable without making actual changes to the submission. The solution to this sort of error is to try to do the merge locally and find out what the actual problem is and then re-submit an update.
  3. Abandoning and bringing in a new patch. This is of a last resort because you can't figure out what the real problem is.

Jenkins Intermittent Failure

For some yet unknown reason it may happen that Jenkins have intermittent failure and thus impact your build.
Look for typical message:


Jenkins error example
[ssh-agent] FATAL: Could not find a suitable ssh-agent provider
[ssh-agent] Diagnostic report
[ssh-agent]  Java/JNR ssh-agent
[ssh-agent] hudson.remoting.RequestAbortedException: java.io.IOException: Unexpected termination of the channel
................
FATAL: [ssh-agent] Unable to start agent
hudson.util.IOException2: [ssh-agent] Unable to start agent
................
Finished: FAILURE


To address the issue just hit the reply button in Gerrit add keyword 'recheck' or 'reverify' (do not enter the ') to the submission that failed. This will automatically retrigger the verify job.
If the job was a merge job, then use the 'remerge' keyword. It will automatically retrigger the merge job.


Submitting a draft feature

As part of the Development Best Practices, it is suggested to commit code multiple times a day. One may argue on the value of submitting code multiple a day if the code you are submitting does not bring value (working functionality) to the community. Developing a complete feature may take days or weeks and until it is complete it may not bring value - but will if work is being shared. Consider submitting unfinished code as an opportunity to show work in progress and get early feedback. However, as we do not want to break the CI paradigm of "Don't break the Build" by committing+merging unfinished work, Gerrit has a way to show work in progress by using the "Draft Feature" capability - however you can commit outside of the draft as long as you mark the review as WIP or "do not merge".

We are making the assumption that developers are working in a feature branch (named story-1 for the sake of the example)

To submit draft code in Gerrit, from a feature local branch, enter from your terminal the following:

git review -D

The name of the local branch (story-1) is used by Gerrit to set the topic.

You can perform the above command as often as you need until the developer has not completed his work. The CI build system is automatically triggered.

These commits CAN'T be +2 and merged in Master.

Once a developer has finished developing the functionality and need all these commits to be merged into Master, the developer will need to use the Gerrit UI and click for each commit the "Publish" button. The committers will then have 36 business hours to complete the review and merge the code into Master branch.

This Gerrit screenshoot illustrates 2 "Draft Feature" of topic: story-1 

Branch Topic

Running a Command within Gerrit

Gerrit provides capabilities to run some command on the tip of the branch.

Note: all the command mentioned below must be entered without the double quote ".

run-cmd

Run-clm

CLM jobs can be triggered on demand after posting the comment "run-clm" in your Gerrit change.

The CLM jobs are still scheduled to run every Saturday, this feature can be useful for debugging on demand. 

Commenting "run-clm" in a gerrit that is not merged, will not trigger the CLM job based on that revision but will trigger the job based on the tip of the branch.

This job is designed to always run on the latest tip of the branch to avoid inconsistencies on the reports.

Run-Sonar

Sonar job can be triggered on demand after posting the comment "run-sonar" in your Gerrit change.

These jobs are scheduled to run every day, this is used to follow up closely on code coverage progress.

Recheck

In the case Jenkins is facing a failure or your need to re-run the Jenkins Verify job you can do so on demand by posting the comment "recheck" in your Gerrit change.

Remerge

In the case Jenkins is facing a failure or your need to re-run the Jenkins Merge job you can do so on demand by posting the comment "remerge" in your Gerrit change.

Please Release

Release jobs can be triggered on demand after posting the comment "please release" in your Gerrit change.

Release jobs can be seen in Jenkins by looking at job name containing this string "release-version-java-daily". The log file file contains the keyword "autorelease-xyz" with xyz a random number.

Autoreleased job are available in Nexus at https://nexus.onap.org/content/repositories/autorelease-zyz

The link to the autoreleased job is a mandatory input for LF to release the binary into Nexus Release.

These jobs are scheduled to run every day.

14 Comments

  1. The http syntax example has an incorrect path.  Refers to "./git/..." rather than ".git/...".

  2. This sentence:

    "In such case you need to have Gerrit generating a password for you (User Account->Settings->HTTPS Password->Generate Password)."

    needs to be in the section labeled "HTTP Sequence of Events" instead of an aside under the "SSH" section.

    And, the URL to set that passwd is: https://gerrit.onap.org/r/#/settings/http-password  

  3. Thanks Dominic Lunanuova for your suggestions. I have made the changes.

    One thing you may not know is that the wiki is public, meaning you can edit and make changes by yourself for the benefit of whole community.

  4. Please explain the exact sequence of steps to download a branch that's in review, add a change, and continue the review process in Gerrit.  I believe this begins with "git review -d NNN" where NNN is the change number shown in Gerrit.  That first step works fine, yielding a branch named for the original submitter, but have not figured out the next steps, all my attempts are rejected by Gerrit; e.g., "you are not allowed to upload merges". Thanks in advance.

  5. What is the gerrit process for a group of developers to collaborate on a feature without destabilizing the master branch?

    Does ONAP gerrit have a processes for this?

    As a team we want to share our code with each other as we developer our feature.  Normally we would do this by creating a feature branch; however my understanding is that we are not allowed to create feature branch. 

    1. We got something working using “git review –D –topic JIRA-STORY-ID”

      For the first submission in a repo 

      git commit -sam "blah blah blah"
      git review –D –topic JIRA-STORY-ID

      Any developer can check out the changes,  amends the tip change, then pushes back to gerrit

      git fetch https://uid@gerrit.onap.org/r/a/oom refs/changes/67/chang-id/6 && git checkout FETCH_HEAD
      git add .
      git commit --amend
      git review –D –topic JIRA-STORY-ID

      The fetch URL can be constructed on the draft review website. There you will find  Download tab on the right side.  Click on it and it will show you the checkout command for the review.    

      Ideally the git review –d JIRA-STORY-ID should work instead of get fetch; however I get 404 

      Other developers can find the review by searching for the topic.  Just place "topic:JIRA-STORY-ID"  in the gerrit website search box.  

  6. What happens when two people both try to amend the same commit and push to git review at about the same time?

  7. Gildas, in section on Merge Conflict, resolution approach #1 says "try to rebase the change".  If I'm reading approach #2 correctly, it refers to approach #1 as "a simple rebase".  Can you clarify what exactly the steps are for #1.  i.e. is it a sequence of git commands, or is it a button on gerrit UI?

    Also, are there restrictions on who can merge code to resolve a conflict?  I recently tried to #2, but in the end my push was rejected due to not authorized, and ultimately resorted to approach #3.

  8. Dominic,

    To rebase, you can use the rebase button in Gerrit UI. I clarified a bit the doc for that.

    Only Committers can provide a code review with a + 2 and merge the code.


    I have been facing this situation, when I was trying to perform a second code submission where as the first one was not yet approved.

    To circumvent this issue here is what I do:

    1) Work on my first code submission and run the git commands: git add -A, git commit -s and the git review

    2) Run the 2 following cmds:

    git fetch origin
    git checkout origin/master

    3) Work on my second code submission and like in step 1) run the git commands: git add -A, git commit -s and the git review

    This approach allows to make multiple small commits and increase your chance for being merged.


  9. The "run-sonar" command (gerrit comment) appears to have little value, as the Sonar analysis produced does not include the changes made in the patch set (to be reviewed). At least for the repos where I have made changes it is necessary to have the commit approved before the analysis can be run on the new or modified code. Has anyone else experienced the same problem? Is there an open issue for this?

      1. Thanks for this hyperlink to your question. I am in fact running SonarLint in my IDE, and I also have my own local SonarQube server. However, the out-of-the-box rules I am using appear to be different to those in the ONAP set-up. I see zero violations locally. I do not have visibility of the ONAP code smells until the analysis is run. Is the Quality Profile configured in ONAP's Sonar up to date?

  10. What does all the "cut" stuff mean?

        --[/cut]--

    Or are they just broken formatting tags?

    1. I think it just means the start/end of the section to be copy-pasted.

      I would edit the page to use a different Confluence widget and remove those "cut" comment lines.