This is a guide for software developers and testers about the continuous integration (CI) resources and processes used by the project and supported by the Linux Foundation.
CI/CD Network Resources
These resources require a Linux Foundation identity.
URL | Description |
---|---|
https://identity.linuxfoundation.org | The Linux Foundation identity management web site. |
https://gerrit.o-ran-sc.org | The Gerrit code review server hosts the Git repositories and supports the review and merge workflow. The review process basically requires all users to follow something like a git pull-request process, but restricts the publication (push) of private branches. |
https://jenkins.o-ran-sc.org | Jenkins is the continuous-integration server aka the build server. All users can see the contents of the Jenkins; no users can directly modify the configuration nor start a job in this Jenkins. Jobs are configured by Jenkins Job Builder (JJB) files in the ci-management gerrit repository. |
https://jenkins.o-ran-sc.org/sandbox | The Jenkins sandbox is a place for testing Jenkins job configurations. After requesting access, users can create jobs, reconfigure jobs, trigger builds etc. New JJB templates should be tested in the sandbox before submitting for review and use on the main Jenkins server. |
https://jira.o-ran-sc.org | Jira is the web site that supports agile development with epics, user stories, and especially issues (bug reports). |
https://nexus.o-ran-sc.org | Not heavily used by this project because Java is not a key technology, this Nexus 2 repository holds Maven (jar and pom) artifacts produced by builds. Snapshot and staging builds are all deployed to this repository. Release artifacts are created by promoting artifacts manually from the staging repository after suitable approval. Publicly accessible to users without credentials. All users should be able to access and browse artifacts through this URL. |
https://nexus3.o-ran-sc.org/ | This Nexus 3 server stores project Docker images and also mirrors external registries. Supports the following:
Access to these registries requires authentication with this well-known username and password:
These credentials provide read-only access to all the registries above. Only the Jenkins server has write access to the snapshot and staging registries. |
https://sonar.o-ran-sc.org | Sonar analyzes Java and Python code for quality issues and code coverage achieved by unit tests (JUnit, tox). |
Development Procedures and Policies
This section guides the developer in submitting code, reviewing code, tracking the status of builds and requesting creation of release versions. These recommended practices come from the Linux Foundation.
Always create a branch
When working with a git repository cloned from Gerrit you can create as many local branches as you like. None of the branches will be pushed to the remote Gerrit server, the branches remain forever private. Creating branches for each task will allow you to work on multiple independent tasks in parallel, let you recover gracefully from various situations, and generally save aggravation and time. Also see these instructions on tagging and branching for releases:
Tagging and Branching Steps Process
Write good git commit messages
The Linux Foundation strongly recommends (and eventually may enforce) Gerrit commit message content. A git commit message must meet these requirements:
- The first line should have a short change summary, up to 50 characters
- The second line must be blank
- The body of the commit message should have a detailed change description
- The line before the footer must be blank
- The footer (last block of lines following a blank line) must consist of these lines:
- Issue-ID: line with a valid Jira issue number, composed and inserted manually by the committer
- Change-Id: line, which is automatically generated and inserted by git review
- Signed-off-by line, which is automatically generated and inserted by git commit
An example is shown below:
Null check for ClientResponse NullPointerException might be thrown as cres is nullable here Issue-Id: PROJECT-999 Change-Id: I14dc792fb67198ebcbabfe80d90c48389af6cc91 Signed-off-by: First Last <fl1234567890@my-company.com>
Using Gerrit
The project uses Gerrit to automate the process of reviewing all code changes before they are committed to the Git repository. For a tutorial on git you might start here:
Also see this guide published by the LF Release Engineering team about using Gerrit:
https://docs.releng.linuxfoundation.org/en/latest/gerrit.html
Prohibited Content
Gerrit is designed to host text files – source code. It enforces a size threshold on every commit, the default limit is 5MB. Further the Linux Foundation prohibits committing binary files such as compiled executables, jar files, zip archives and so on. An exception is made for binary picture (image) files in GIF, JPG and PNG formats, but the size limit must still be honored.
Quickstart Guides
The quickstart guides below describe the command-line procedures for performing common tasks on Gerrit. The command-line tool "git review" is the most reliable and can be used on any platform. Windows users should install "Git Bash" to gain support for command-line git.
Quickstart: Create and submit a change for review
git checkout -b my-local-branch |
Quickstart: Revise your open gerrit review
git checkout my-local-branch |
Quickstart: Revise any open gerrit review
# Look up the change number shown top-left in Gerrit web, here "999". |
Quickstart: Resolve a conflicted review
git checkout master |
Quickstart: Squash commits after you forgot the "--amend" flag
# |
Reviewing and merging on Gerrit web site
Submitted reviews with changes should appear in the Gerrit web interface. The Jenkins job builder will publish test results, giving "Verified +1" if the test succeeds and -1 if the test fails. A contributor or committer can review it with a -1/0/+1. A committer then must approve it with a +2 rating and merge the code to the master branch.
The committer may take any of several actions, such as clicking on the "Reply" button, adding reviewers, adding a review comment, and moving the flags to +2 and +1
Once a committer/contributor approves it, the code can be merged to the master branch.
Releasing your project
When the project determines that an artifact in a staging repository is ready for release, a release can then be performed as follows:
- Find the Jenkins job that created the release candidate. Look among its output logs for the file with the name of the staging repository, it will have a URL like this:
- https://logs.o-ran-sc.org/production/vex-yul-o-ran-sc-jenkins-1/common-dataservice-maven-dl-stage-master/4/staging-repo.txt.gz
- Open a ticket with the LF helpdesk to sign the artifact(s) in the staging repo and promote them to the release repo. Example request is below.
- Send email to helpdesk@o-ran-sc.org with CC to affected people, only To and Cc people can see the ticket status
- Supply the Jenkins job URL and Jenkins log URL from above.
- Supply the name of the autorelease repository.
- Add a tag for the release on the Gerrit web site.
Example release request:
Please release the PROJECT-NAME jar and docker image at version VERSION Stage job: https://jenkins.o-ran-sc.org/job/PROJECT-stage-master/201/ Logs: https://logs.o-ran-sc.org/production/vex-yul-o-ran-sc-ra-jenkins-1/PROJECT-stage-master/201/ Autorelease repo name: autorelease-1150 Thanks in advance
Once complete the artifact(s) will appear in the Nexus2 release repository and/or Nexus3 release registry.