Gerrit Development Workflow

1. Developer clones component repository from Gerrit server https://code.rdkcentral.com/r/ into local workspace.

git clone https://user@code.rdkcentral.com/r/component1

Note: Individual users can use their RDK passwords to authenticate Git operations over HTTPS. There is no need to generate a HTTP password within the Gerrit Web UI.

Note: In addition, the developer may need to configure their Git identity on the cloned repository. The email address that git uses should match the email address listed in gerrit.

Example commands to run are as follows:

git config user.name "John Doe"
git config user.email "john.doe@example.org"

2. Set up the commit-msg hook to add Change-ID footer to commit messages.

The commit-msg hook is installed in the local Git repository and is a prerequisite for Gerrit to accept commits. The inclusion of the unique Change-ID in the commit message allows Gerrit to automatically associate a new version of a change back to its original review.

Note: To download the commit-msg script from the Gerrit server to your local system use and make the hook file executable:

curl -o <local path to your git>/.git/hooks/commit-msg <your Gerrit https URL>/tools/hooks/commit-msg
chmod u+x ~/component1/.git/hooks/commit-msg

3. Developer works on the change, committing to local clone.

The Developer creates a topic branch in the local work area, makes the necessary changes and then squashes the commits prior to pushing for review.
Note: To create a topic branch use:

git checkout -b <Branch Name>

Each commit constitutes a change in Gerrit and must be approved separately. It is recommended to squash several commits into one that represents a change to the project. It is possible to squash a series of commits into a single commit before publishing them, using interactive rebase `git rebase --interactive`. 
It is important to preserve the Change-Id line when editing and there should only be one "pick" entry at the end of this process. The end result is to submit one change to Gerrit.

4. Developer pushes the new change to Gerrit for review, i.e. to refs/for/master.

git push origin HEAD:refs/for/master

When interfacing with Gerrit you push to a virtual branch, /refs/for/<branch>, representing "code review before submission to branch". Gerrit will subsequently assign a unique URL for the change, to facilitate access and review via the web UI.

Note: HEAD is a symref to the most recent commit on the current branch. When you change branches, HEAD is updated to refer to the new branch's latest commit.
Note: The refspec in the git push operation takes the form source:destination (source is the local ref being pushed, destination is the remote ref being updated).

5. Review notifications and addition of new reviewers.

The Developer may request feedback by adding additional reviewers via the Gerrit web GUI or alternatively by specifying details on the command line when pushing changes to Gerrit. Component owners/reviewers/approvers, defined as specific groups in the external LDAP system, will be added by default.
Note: additional reviewers can be added using ``%r=user@mail.com`` syntax during the push operation on the command line.

6. Run BlackDuck, copyright scanning and build on code submission.

If applicable, BlackDuck, copyright scanning and build jobs will be triggered from Jenkins. The output of these jobs is integrated into the Gerrit voting process via custom labels and will reflect any 'red flag' in a file that has new code changes, whether introduced in the new Change/Patch Set or not.

7. Code review and scoring process

Reviewers can comment on and score a given change.
The default set of rules for enabling a code change for submission requires a Code Review score of +2 and a +1 score on any mandatory Gerrit labels configured for the project.
The result of the scoring process and validation rules is to enable the Submit action on the Gerrit Web UI and subsequent merge capability to the target branch.

Label: Code Review For a change to be submissible, the latest patch set must have a '+2' value approval in this category or label, and no '-2 Do not submit'. Thus -2 on any patch set can block a submit, while +2 on the latest patch set can enable it.

Labels: Blackduck/Copyright/Component-Build For a change to be submissible, the change must have a '+1' score on these labels, and no '-1 Fails'. Thus, '-1 Fails' can block a submit, while '+1' enables a submit.

Note: Review input is generally referred to as labelling with a positive/negative score.

8. Submit change

Only authorised users i.e. component owners and component approvers can submit the change allowing Gerrit to merge it to the target branch as soon as possible. A change can be submitted, having satisfied the approval conditions described earlier, by clicking the 'Submit Patch Set n' button within the Gerrit UI.

9. Abandon change

A concious decision is made to abandon the change based on the review outcome. The component owner or an authorised user may abandon the change by clicking the "Abandon Change" button. The abandoned changes are not removed from the Git repository and could be restored at a later stage.

10. Submitted, Merge Pending

The change depends on another change that is still in review. In this case the change will be merged automatically once all its dependencies are submitted and merged.

11. Change needs to be reworked

Rebase and amend the commit and push to `refs/for/<target branch>` again.
In order to submit a reworked change it is necessary to push another commit that has the same Change-ID (as the original) in the message.
This is the mechanism Gerrit uses to associate or link the two items. The `--amend` option to git commit prevents a new Change-ID being generated by the commit-msg hook.
The basic steps are outlined below:

git fetch https://user@code.rdkcentral.com/r/component1 refs/changes/02/2/1 && git checkout FETCH_HEAD

where the numbering scheme for fetching the changes is as follows:
refs/changes/<last two digits of change number> <change number> <patch set number>

Note: Gerrit will specify this fetch URL, the developer just pastes it into the command line.

[Edit the file]
git commit --amend
git push origin HEAD:refs/for/master
A new patch set is now appended to the Gerrit review item, and this will go through the same review process as before.

Note: The 'change number' referenced above is different to underlying Git commit ID.
Note: Patch-sets are numbered (starting from 1) for each review, and incremented whenever a change is amended with another Git commit.
Note: FETCH_HEAD is a Git symref and shorthand for the head of the last branch fetched and is valid only immediately after the fetch operation.

12. Automatic merge of changeset to target branch after successfully submitting

13. Gerrit merge failure as a result of a conflict

Essentially this means that the remote branch has evolved since this change was started and now software conflicts with changes in the remote branch. The developer must resolve the merge conflicts in their local clone and then push another patch-set.
The process is resumed at step 4, with the important distinction of committing with the --amend option, once the developer pulls the latest changes.

Note: A summary of the steps involved, assuming the local branch still exists: 
Rebase the local branch to the latest state of origin/master; Resolve all conflicts; Commit with the `--amend` option; Push changes to Gerrit for review. After this change a new patch set is created for the change.

Note: If the local branch no longer exists, the steps are as follows :

git checkout -b topic_branch
git fetch https://user@code.rdkcentral.com/r/rdk_component_1 refs/changes/58/58/2 && git checkout FETCH_HEAD
git rebase origin/master
[Edit the conflicting file, cleaning up the <<<<, ==== >>> markers surrounding the conflicting lines]
git add <file>
git commit --amend
git push origin HEAD:refs/for/master