User Tools

Site Tools


submitting_to_gerrit

Submitting changes to Gerrit

Set up

If you have not set your system up yet, please jump over to the Setup Instructions.

First patch to Gerrit

Even if you are experienced at submitting patches to open source projects and with git, gerrit may feel unfamiliar at first. Consider asking for a mentor to help walk you through the first patch, there are people who are happy to help with this (ask in the commit message, or on the mailing list if you'd like some tips even before submitting)

Creating commits and submitting to Gerrit

To submit a patch to the Gerrit, follow the following outline:

  • Switch to the project directory and perform local development. Some developers prefer to work in the branch they are going to submit to, others prefer to make a branch off the head of the target branch and work there. Which approach you choose is mostly a factor of comfort with different git commands.
  • Stage the revised content by executing the following command:
    $ git add <Revised_File>...
  • Commit the revised content by executing the following command:
    $ git commit -s

    The -s switch will cause the commit to have the mandatory Signed-off-by: line - gerrit is configured to reject pushes without this line. The commit hook will cause a Change-Id: line to be added, which is also mandatory.

  • If there is a bug ticket this change applies to, it is suggested to add it when editing the commit message, this goes down in the same block as the Signed-off-by:, add a line with Bug: followed by the URL to the Jira ticket. A bug reference is not mandatory, but tying to a bug that is approved for fixing will make acceptance of your patch easier.
  • Push the patch to Gerrit by executing the following command:
    $ git push origin HEAD:refs/for/<remote_branch_name>
  • For new patches, open the URL that the server has just given you and add reviewers to your change.
  • New features should be pushed to their own development branch, if they need one, or to master if the new feature is simple enough. Bug fixes should go to both master and to the release branch that they apply to (e.g., “1.2-rel”). You do not have to make two separate commits and push both; once one is pushed, the gerrit interface should allow you to cherry-pick it to others, which will mean they automatically have the same Change-Id. At certain times during the development cycle, regular merges from the active release/maintenance branch may be made by an administrator, so the initial target should be the release branch, the submit to master may end up ignored in favor of the mergeback. Although the gerrit interface does show cherry-picks made this way, it is easier for reviewers if, when gerrit offers the chance to edit the commit message a line is added which says something along the lines of “This is a cherry-pick of a change for 1.3-rel”.
  • If you are submitting a lot of patches a git alias can speed things up slightly. Here is an example setup:
    $ git config --global alias.push-for-review "push origin HEAD:refs/for/master"

    Which then allows running:

     $ git push-for-review

    You can of course pick any name for your aliases that you like.

Adding reviewers

It is your responsibility to add reviewers to your change. You can add anyone that you want and it's a good idea to add other subject matter experts for their opinions. Any change needs to be approved (+2) by a maintainer or sub-maintainer, so you should ensure the appropriate ones have been added to the review. For the complete list of maintainers and subject matter experts, see the page Projects and Functions.

Disclaimer: picking the right reviewers is admittedly tricky. Building experience with the project will also build experiece with selecting appropriate reviewers. We can do better at this part - if you have ideas for improving things, please <strike>yell at us</strike> provide some constructive criticisim how things could be better.

Jenkins Verification

The system will verify that your change builds in all the scenarios supported by the project. To do this, the user “jenkins-iotivity@iotivity.org” is added to the reviewer list. Normally, maintainers and even reviewers may be reluctant to approve your change unless it is clear it is going to apply. jenkins-iotivity will give your change a +1 if all of the required builders complete successfully. Note: jenkins-iotivity is supposed to get added automatically. If this hasn't happened after a while, add the user manually.

If there are problems with the jenkins build, you should check to see what the issues are and resubmit after fixing. Sometimes there are problems not caused by your change - these might be infrastructure issues, or someone else committed a change which impacts a build on a specific platform thus causing yours to fail. Such things “should not happen” but this is a complex set of permutations and resources, and sometimes it does happen. If you believe a problem is not your fault, and that the problem has been resolved, you can ask for a reverification by submitting a comment to your own change with the word “reverify” in it.

Here are the builds executed by Jenkins (some may not apply in some circumstances).

Updating existing changes

To update an existing change, you need to edit the commit and re-submit it the same was as was done initially.

  • Switch to the project directory/branch and make the required changes.
  • Stage the revised content by executing the following command:
     $ git add <revised_file> ... 
  • If the commit you want to update is the last one, simply amend that commit, with the following command:
     $ git commit --amend 
  • If the commit you want to update is not the last one, locate its commit ID and run the following:
    $ git commit --fixup <commit_ID>
    $ git rebase -i --autosquash 
  • In both cases, it is critical that the Change-Id line remain unchanged and close to the bottom of the commit message
  • Once done, push the changeset again to the server, as was done initially
     $ git push origin HEAD:refs/for/<remote_branch_name> 

Draft changes

If you have work that isn't ready for acceptance but something you'd like to have initial reviews on, you can use a Gerrit feature to push draft reviews. The review will be visible only to you and to others you may add as reviewers in the Web UI, rather than to everyone browsing Gerrit.

The procedure is the same as above for both the initial push as well as for updating. The only difference is that you should push to refs/drafts/<remote_branch_name> instead of refs/for/<remote_branch_name>

submitting_to_gerrit.txt · Last modified: 2017/12/08 16:25 by Mats Wichmann