Page tree
Skip to end of metadata
Go to start of metadata

This page describes how to contribute code reviews to ONAP through Nordix. Developers who are contributing code as reviews to ONAP must use this process. This process keeps the reviews on the Nordix master branch in lock step with reviews on the ONAP master branch.

This process assumes that your userid on the Nordix gerrit and the ONAP gerrit are the same. You can check if this is the case by clicking these links

The process may work in cases where your Nordix and ONAP userid differ but we have not tested that case.

Contents

1 Initial Configuration

1.1 Permit the Nordix Gerrit to upload changes to ONAP on your behalf

You must store the Nordix gerrit public key in the ONAP gerrit in order to enable pushing of reviews directly from the Nordix Gerrit to the ONAP Gerrit under your username. You need only carry out this step once.

  1. Log onto the ONAP gerrit
  2. in Settings→SSH Public Keys, click "Add Key..." (or click this link https://gerrit.onap.org/r/#/settings/ssh-keys)
  3. Paste the infra@nordix.org public key below into the text box

    ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQCdyLRXDIU4w/0H/kZa+2Fw/NLPTyW83F9cQqrahGybbff/pY3CxBKUqRefIp6SLjcR5TjrWOLVO6hlan+nzUzVahlgim8YIGYiD7l6ZuWBvlt/WpqqZOswRLKsgQgTDBUNFXl4V++bsZfbJwlv1QnNaeXGYdfGulXTnQ0wk4+/rBhPXqKVIPJyjnnrz1yCxwyRGOtB9hzSiG1VoKEoddgqIydRnxPQER7K5mc3E6CmvNr8FB5sbo+urT8EVLlb9Df8a7G0XRfMrM0z+1mFjlXG6ckvbIrlfJjQkeK00cXiFwwAmRQeHKZEQrl9++uhjcueIT0TYnGMW7ZW/Hl6NfV8z21pcj+erD3ltDXn3yZjlzf44ekvtNGegJ7hlB7mSdY17rk46QPSlPtPDeibZFj33c+jhZVFeB8PV7DOfXhqtNEVCZ/GlajQlgqbJqy1ILVftD/AhZpyEK0P6j8RiP7IF+rKVrdLsnoXPuHPMV+l+JKJE7STDHiCST0Opn5+WbQhiysDkORCfZMa+q02+/V4X6Khc97ws2LVJU19EQpqGSTYRew44E/cPGFMd3MvlyvzULV56XEtGESAYGAJdgj8g+zif8R4HjfgXo0KRgnz9yk3UU9qo2QZ1aqfu7+mO5r33cVk5ZVUIp3r0f7SD6OEOpj2nlc+cIaV6XRlF/BDYQ== infra@nordix.org
  4. Click "Add"

1.2 Add Repository Jenkins JJB Jobs

Jenkins jobs are written in the JJB (Jenkins Job Builder)  language, a dialect of Yaml. To create or amend your Jenkins job:

  1. Clone the Nordix infra/cicd repository

    git clone ssh://<your-userid>@gerrit.nordix.org:29418/infra/cicd
  2. Create or amend the JJB yaml file for your job under the jjb directory in the cloned infra/cicd repo
    Note that by convention, there are subdirectories under the jjb directory for the various ONAP projects, create your new JJB file in the appropriate directory.
  3. Submit your new or updated JJB yaml files as a review

There are three jobs which must exist on the Nordix Jenkins for all ONAP cloned repositories. To create the jobs

  1. Copy working jobs for another ONAP cloned repository in the infra/cicd/jjb directory
  2. Change the fields name, project, and project-name to the values for your project in all three yaml files

For example, for the OOM project, the fields are as follows:

	name: oom-push-upstream
    project: oom
    project-name: oom

For the policy/apex-pdp project, the fields are as follows:

    name: policy-apex-pdp-push-upstream
    project: policy/apex-pdp
    project-name: policy-apex-pdp

You can check running and/or completed jobs on the Nordix Jenkins.

The three jobs to be created are as follows:

  1. The Verify Job: <project-name>-verify-jobs.yaml This job is called when you submit a review to your project on the Nordix gerrit. You specify the branches that you want the verify job to trigger on. Since we should strive for quality code, having verify jobs for your project on Nordix Infra helps you to send your changes to upstream with minimum issues so the reviews in upstream could go faster.
  2. The Push Upstream Job: <project-name>-push-upstream-jobs.yaml This job pushes your reviews upstream from the Nordix master branch to the ONAP master branch. You activate by posting a comment containing the magic word "push-upstream" to your review in the Nordix master  branch. Please ensure your review on Nordix Gerrit got Verified+1 from verify job running on Nordix Jenkins before sending the review to upstream.
  3. The Rebase Job: <project-name>-rebase-jobs.yaml This job keeps the Nordix master branch synchronized with the ONAP master  branch in the repository. It is called whenever code is merged on the ONAP gerrit repo. It pushes the merged code from the ONAP master branch to the Nordix master branch.

1.2.1 Use scripts to generate the three Nordix Jenkins jobs

nordixJobs.sh

To make the process easier and quicker for creating the push-upstream, rebase and verify jobs for Nordix, the above nordixJobs.sh shell script and setup.txt will reliably do it.

  1. Place the two files in whatever directory you want to create the three yaml files.
  2. Run 'sh nordixJobs.sh' and you will be prompted for the name of the root project, eg: 'policy'
  3. Next you will be prompted for the name of a child project if one exists, e.g, 'pdp' (If there is no child project, just hit [Enter])
  4. The three yaml files in either case (with or without child projects) will be created in a folder with the same name as the root project in that directory.
    - chosenDirectory
         - policy
              - policy-pdp-push-upstream-jobs.yaml
              - policy-pdp-rebase-jobs.yaml
              - policy-pdp-verify-jobs.yaml

Simple edits to the nordixJobs.sh script can improve speed and ease of use, e.g, include your own 'git add .' and 'git commit -am "Add rebase/push/verify jobs for $rootProject\/$childProject"' etc...

1.3 Set your git "user.name" to be your Linux Foundation ID

In order for the review push from the Nordix Gerrit to the ONAP Gerrit, your review must be submitted with your Linux Foundation ID.

Check that your git user name is your Linux Foundation ID with the command:

git config --global --list

If the user.name is not set correctly, set it with the command:

git config --global user.name "<your linux foundation ID>"

1.4 Configure git review to use the Nordix rather than the default ONAP repository

We (and ONAP) use the git review tool to manage reviews. In each cloned ONAP repo, there is a file called .gitreview that configures git review. That file specifies gerrit.onap.org as the hostname of the git repository it will use. You override this setting by configuring properties in your local git installation

Set the Nordix host for git review with the following command:

git config --global gitreview.hostname "gerrit.nordix.org"

Set your user name for git review to your user name on Nordix with the following command:

git config --global gitreview.username "<your_nordix_gerrit_user_name>"

2 Submitting a Review

You MUST configure git review to work towards the Nordix gerrit as explained in step 1.4 above in order for git review to work towards the Nordix gerrit rather than the ONAP gerrit.

  1. Prepare your review on the master branch of the Nordix repo that is a downstream of an ONAP repo.
    1. You may work on the review on the master branch from scratch
    2. You may create the review on the master branch by squashing or cherry picking reviews from development branches.
  2. Submit your review to the master branch of the repo on the Nordix gerrit. The process is very similar to that used when working directly towards the ONAP gerrit, see the ONAP process for submitting reviews.

    git add <some content>
    git commit -m "A descriptive message of the change"
    git commit -s --amend
    <Add your ONAP issue ID and a full description of the change as described in the ONAP process>
    git review
  3. Your review is now submitted to the Nordix gerrit.
  4. Upstream your review to the master branch of the repository on the ONAP gerrit by logging onto the Nordix gerrit and posting a comment with the word: 

    push-upstream

    This triggers the Jenkins job that upstreams your review to the ONAP master branch.
    Note: Never +2 or commit/merge a review directly on the Nordix master branch as this will cause the ONAP and Nordix master branches to diverge.

    It's also possible to upstream your review on ONAP gerrit as a Work-In-Progress change. In order to do that login to the Nordix gerrit and post a comment: 

    push-upstream wip

    Omitting the wip option when pushing updates to a wip change doesn’t make change-ready again. 
    To remove the wip flag from a change on ONAP gerrit. Please login to the Nordix gerrit and post a comment: 

    push-upstream ready
  5. The review is approved and merged in ONAP. When the review is merged in ONAP, the merge triggers a push of the review in the Nordix cloned repo. The Nordix cloned repo is therefore always in lock step with the ONAP upstream original repo.
  6. When the review in upstream gets merged, the status of your original review on Nordix Gerrit will also be automatically closed since Gerrit associates reviews using ChangeId and when sync job brings your commit from upstream to Nordix Gerrit, it will be in Merged state. No further work is required on your side.

Note 1: Steps 1. to 3. may be repeated to update reviews where changes to reviews are required.

Note 2. Only the original author can use 'push-upstream' on a commit. Sometimes it might be necessary that a different developer takes over a commit and needs to execute this. In that case you need to reset the author (and sign it) for the commit:

rest commit author
git commit -s --amend --reset-author


2.1 Getting convenience scripts

  1. Get the onap review scripts.

    git clone https://gerrit.nordix.org/infra/tools

    The scripts are in the onap/onap-reviews directory.

2.2 Cloning a Repository

  1. Clone the repository you wish to work with. The example command below clones the policy/core repository to the local directory core. The gerrit-userid field is your userid on the Nordix and ONAP gerrit.

    heis-clone.sh <gerrit-userid> policy/core core

    This script clones the repository you require, creates a commit hook that signs your commits, and creates an upstream entry in the .git/config file of the newly cloned repository.

    1. Note: is you use Windows, if needed install the Windows Linux Sub-System, and dos2unix. In bash ensure that git and scp already works.

      dos2unix -n infra\tools\onap\onap-reviews\heis-clone.sh infra\tools\onap\onap-reviews\heis-clone-win.sh
      bash -i infra/tools/onap/onap-reviews/heis-clone-win.sh gerrit-userid onap/policy/core policy/core

2.3 Creating a Review and Submitting it through Nordix to ONAP

The review is created on the Nordix gerrit and is then transferred to the ONAP gerrit.

  1. Make whatever changes and additions you require to your code and check it in locally.

    git add .
    git commit -am "My review message"
  2. Add an ONAP issue ID to the commit message: Issue-ID: <ONAP-JIRA-Issue-ID> where the ONAP-JIRA-Issue-ID field is some issue in the ONAP JIRA.

    git commit -as --amend
  3. Push your commit to the Nordix gerrit as a review.

    git review
      or 
    git review <branchname>

    Note: If submitting a review to a branch make sure you use git review branchname    e.g.  git review guilin to add your review to the remote branch called guilin

  4. You can check that you review is on the master branch of the Nordix gerrit (or appropriate branch if you specified a different branch).

  5. Your review is now verified on the Nordix Jenkins. If verificaiton of your review fails for whatever reason, you can re-run the verify job by posting a comment on your review on the Nordix gerrit containing the magic word "recheck" or "reverify".
  6. Transfer the review from the Nordix gerrit to the ONAP gerrit. Post a comment on your review on the Nordix gerrit containing the magic word "push-upstream". You can now check that your review is on the master branch of the Nordix gerrit.

3 Downloading a review for rework and resubmitting the review

3.1 Getting the review

If you have deleted your copy of the review you were working on from your local machine or if you wish to work on a review submitted by someone else, you must download the review from the Nordix gerrit.

  1. Clone the repo from the NORDIX gerrit if you do not already have a cloned copy of it, as explained in Sectio 2.3.1 above.
  2. Use git review to list the available reviews for download.

    git review -l
    1017  master  Add event carrier plugin for CDS
    Found 1 items for revie
  3. Download the review using git review

    git review -d 1017
    Downloading refs/changes/17/1017/7 from gerrit
    Switched to branch "review/<your_gerrit_id>/1017

3.1 Uploading a Modified Review and Submitting it through Nordix to ONAP

The review is created on the Nordix gerrit and is then transferred to the ONAP gerrit.

  1. Make whatever changes and additions you require to the review and check it in locally.

    git commit -as --amend
  2. Push your commit to the Nordix gerrit as a patch set on an existing review.

    git review
      or 
    git review <branchname>

    You can check that you review has a new patch set on the master branch of the Nordix gerrit.

  3. Transfer the review from the Nordix gerrit to the ONAP gerrit. Post a comment on the Nordix gerrit containing the magic word "push-upstream". You can now check that your review has a new patch set on the master branch of the ONAP gerrit.

4 Actions after new release branch has been created in ONAP

When a new release branch has been created there is a number of steps to perform.

  1. Step the version number of the product on the master branch, e.g. from 1.0.4 to 1.1.0. Note! Don't forget the version.properties file!
  2. Add the new branch to the Jenkins configurations of the product. These are located in the "ci-management" repo, at least in the files "jjb/<project>/<product>.yaml" and "jjb/usecases/<use case>.yaml"
  3. Remove the "<imageTag>latest</imageTag>" tag from the pom file with the "docker-maven-plugin" in the release branch.

7 Comments

  1. Liam Fallon Looks pretty good. Did some small updates.

    Once we are ready with this, the link can be distributed to EST ONAP developers so everyone can know the new wow.

  2. Liam Fallon Fatih Degirmenci Conor Ward

    One suggestion here - why don't we remove +2 & merge rights from Nordix gerrit. ?? So that by mistake also no one is able to break the process and code is always reviewed and merged in ONAP gerrit.

    I know for infra & Jenkins jobs kind of stuff we still need to review & merge them in Nordix gerrit. But for that we can have few folks having the rights.

  3. Ram Krishna Verma Issue is lack of time to configure it.

    All the projects we have on Gerrit inherit rights from All-Projects so we need to created new project for ONAP to configure permissions. If you have time to investigate this and fix, let me know.

    If not, things will stay as they are until I find time.

  4. Ram Krishna Verma and others who are working on ONAP on Nordix Gerrit: +2/submit rights have been disabled on mirrored projects as of this morning and branches are switched to master so the workflow described on this page is in full effect.

  5. git config --global user.name "<your linux foundation ID>"

    weird, this does not work for me.

    git commit --author <your linux foundation ID>

    this command works for me...

  6. In order to change the author of a specific commit (where one person is taking over on the commit)

    git commit --amend --author "lfid <emailname@est.tech>"

  7. This exact process works for ORAN-SC repos too ... just replace all occurrences of "gerrit.onap.org" with "gerrit.o-ran-sc.org"