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
- Username on Nordix Gerrit: https://gerrit.nordix.org/#/settings/
- Username on ONAP Gerrit: https://gerrit.onap.org/r/#/settings/
The process may work in cases where your Nordix and ONAP userid differ but we have not tested that case.
Contents
Table of 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.
- Log onto the ONAP gerrit
- in Settings→SSH Public Keys, click "Add Key..." (or click this link https://gerrit.onap.org/r/#/settings/ssh-keys)
Paste the infra@nordix.org public key below into the text box
Code Block 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
- 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:
Clone the Nordix infra/cicd repository
Code Block language bash git clone ssh://<your-userid>@gerrit.nordix.org:29418/infra/cicd
- 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. - 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
- Copy working jobs for another ONAP cloned repository in the infra/cicd/jjb directory
- 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:
Code Block |
---|
name: oom-push-upstream project: oom project-name: oom |
For the policy/apex-pdp project, the fields are as follows:
Code Block |
---|
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:
- 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.
- 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.
- 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
View file | ||||
---|---|---|---|---|
|
View file | ||||
---|---|---|---|---|
|
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.
- Place the two files in whatever directory you want to create the three yaml files.
- Run 'sh nordixJobs.sh' and you will be prompted for the name of the root project, eg: 'policy'
- 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])
- 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:
Code Block | ||
---|---|---|
| ||
git config --global --list |
If the user.name is not set correctly, set it with the command:
Code Block | ||
---|---|---|
| ||
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:
Code Block |
---|
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:
Code Block |
---|
git config --global gitreview.username "<your_nordix_gerrit_user_name>" |
2 Submitting a Review
Warning |
---|
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. |
- Prepare your review on the master branch of the Nordix repo that is a downstream of an ONAP repo.
- You may work on the review on the master branch from scratch
- You may create the review on the master branch by squashing or cherry picking reviews from development branches.
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.
Code Block 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
- Your review is now submitted to the Nordix gerrit.
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:
Code Block 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:Code Block 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:Code Block push-upstream ready
- 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.
- 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 for the commit:
Code Block | ||||
---|---|---|---|---|
| ||||
git commit --amend --reset-author |
2.1 Getting convenience scripts
Get the onap review scripts.
Code Block language bash git clone https://gerrit.nordix.org/infra/tools
The scripts are in the onap/onap-reviews directory.
2.2 Cloning a Repository
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.
Code Block language bash 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.
Note: is you use Windows, if needed install the Windows Linux Sub-System, and dos2unix. In bash ensure that git and scp already works.
Code Block language text 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.
Make whatever changes and additions you require to your code and check it in locally.
Code Block language bash git add . git commit -am "My review message"
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.
Code Block language bash git commit -as --amend
Push your commit to the Nordix gerrit as a review.
Code Block language bash 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 guilinYou can check that you review is on the master branch of the Nordix gerrit (or appropriate branch if you specified a different branch).
- 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".
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.
- 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.
Use git review to list the available reviews for download.
Code Block language bash git review -l 1017 master Add event carrier plugin for CDS Found 1 items for revie
Download the review using git review
Code Block 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.
Make whatever changes and additions you require to the review and check it in locally.
Code Block language bash git commit -as --amend
Push your commit to the Nordix gerrit as a patch set on an existing review.
Code Block language bash 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.
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.
- 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!
- 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"
- Remove the "<imageTag>latest</imageTag>" tag from the pom file with the "docker-maven-plugin" in the release branch.