This tutorial covers the topics of how to accept committer invitation from LF, how to conduct code review, and how to accept code submission to the Master code branch.
Committers are the gatekeepers of the code repositories. They are responsible for reviewing code submissions, judging their quality and whether the submissions should be accepted and merged onto the Master branches of the Git code repos that they are committers for.
Accepting Committer Invitation
(Note: The newest from LF is that some of their engineers no longer use this process, for which the prospective committers are no longer notified by such invitation, if the new repo is created with an INFO.yaml file. Under the new process, the prospective committers may verify their committer status by looking into the "Groups" listing in their account profile, as described in the next section.)
(Note: the formal process of identifying/promoting committers will be decided by the ToC. It is not covered by this tutorial.)
Each committer request made by the O-RAN open source projects must be submitted to and processed by the Linux Foundation Release Engineering team. At the completion of such processing, Linux Foundation would notify the committers by sending them invitation emails.
These invitation emails are sent from do-not-reply@linuxfoundation.org and subjected "LF Release Engineering Automation has sent you a Linux Foundation ID invite". At the beginning of these invitation emails, it would state something similar to the following: "LF Release Engineering Automation has invited you to join the oran-gerrit-it-dep-committers group...", where the group name (bold text) contains a segment (red text) which is a transformed version of the repo name which this committer right invitation is for. At the end of these invitation emails there is a link to the Linux Foundation ID management platform https://identity.linuxfoundation.org. Following the link and logging on to the ID management web site will complete the invitation/activation process. In the cases where the invited committer does not have a Linux Foundation ID yet, this is the opportunity to complete the ID registration using the same web site.
Because each of these invitation emails is a specific invitation for the recipient to becoming a committer for a specific source code repo, it is important to open each of them that is received and follow the embedded links inside of all received invitation emails to activate the committer role for all the corresponding repos.
Verify Committer Status
We can check for which repos that we are a committer of by going to the "Settings" menu option after logging in to the Gerrit site, and finding the "Groups" section where all the committer groups that we are a member of are listed. There should be one of such group for each repo, with the group name in the format of oran-gerrit-it-dep-committers.
Conducting Code Review
Code Change Review UI
The bulk of a committer's day-to-day involvement in Open Source development is conducting code submission reviews and deciding whether to accept the submission. Thus it is important for any committer to become familiar with the user interfaces and procedures of conducting code reviews. Actually anyone with a Linux Foundation ID can conduct code review, not just committers. Hence this and the next section apply to all reviewers. However, as we will see soon, there are differences in the user interfaces for committers v.s. regular reviewers, and committers have much greater "power" in deciding whether to accept and actually carry out code merge.
After logging in to the Gerrit site, clicking on a change URL, either by browsing through the list shown by the CHANGES→ Open pulldown menu item on the Gerrit page, or be following the link in a review request, we will see this change review UI below.
Providing Line Specific Review
Line-specific review comments can be provided by clicking on individual file entry from the above review UI, then moving the mouse cursor in the text view window to the specific location where comments are to be provided. Next, typing key "c" will bring up the comment window as shown below, where the line specific comments can be entered. After comments are provided, clicking on "SAVE" button to save comments and close the line specific review box.
These saved line specific comments will not be published yet. They will be sent along with the over-all review reply once that is done.
Over-all Review Reply
Clicking on the "REPLY" button on the review UI will open up the reply panel as shown below. Comments can be entered in the large input area, and the reviewer may provide a Code-Review score. The left side example shows what a regular reviewer sees while the right side example shows what a committer sees when he/she is reviewing a change for a repo for which he/she is a committer. The committer has more reviewing "power" as he/she can give a +2/-2 instead of +1/-1.
It is worth pointing out that there is a "Verified" score for each review. This score is to be generated by automated build/test Jenkins job in future. Currently for repos that do not have the job enabled, no score is shown on the regular reviewer's window. Regardless there is an automated job generated Verified score or not, a committer can also provide his/her own "Verified" scoring.
After the review score(s) and comments provided, clicking on "SEND" to publish the review.
Requesting Specific Reviewers
The same review panel above can be used for requesting specific reviewers. This is done by clicking on the "Add reviewer..." text box, and enter the email address of the reviewer that is to be requested. Gerrit UI will use pop-up bubble to show the person matches with the email address as it is being typed. Once the correct person shows up, clicking on the pop-up to add this person as reviewer. As email will be sent by Gerrit to this person notifying a "review-by-you" request has just been made.
From the code change review UI, there is also an "ADD REVIEWER" button on the left side panel. Clicking on it will open the same reply window where reviewer request can be entered.
Submitting Acceptable Code Change (Committer only)
After all the reviews are done, if the submission has cumulated enough review score on the positive side, --the current standard is to have Code-Review score >= 2 and Verified score >=1, a "SUBMIT" button will appear of the review UI as shown below.
Now a committer can decide that the submission is considered good enough and proceed with merging. Clicking on the "SUBMIT" button will merge the submitted code under this change onto the master branch of the repo. At this point this review is completed and the review UI will also change to indicate the status change. From here on any future cloning of the repo will include the newly merged code change.
Running Tests on Code Under Review
Oftentimes it is not enough just eyeballing the submitted code on the Gerrit UI. It needs to be downloaded, built, and tested. This can be done by the following steps on a dev machine that is used for testing the change submission.
- Find the "DOWNLOAD" button from the change review UI:
- Clicking on the DOWNLOAD button will open a patch download command panel where multiple commands for downloading the patch are provided. For example, if we want to checkout the code change submission, we may click on the "copy" icon at the right end of the first command.
- Now go to a terminal window on the dev/test machine, make a fresh clone of the current master branch of the repo;
- Change dir to the newly cloned repo;
- Using terminal's "paste" option to paste the command for checking out the code change submission patch into the terminal and run it.
- Now we have a complete code submission that we can run build and tests.
