FORUMS
Remove All Ads from XDA
Honor 9 Lite

[GUIDE] Using Gerrit code review

1,297 posts
Thanks Meter: 2,474
 
By nailyk, XDA Ad-Free Senior Member on 17th December 2017, 01:44 PM
Post Reply Email Thread
Purposes of this guide

This guide want to be a how-to use Gerrit, allowing everyone to contribute on AOSP like projects.
Divided in 3 parts:
  1. Now few important stuff needs to be setup before proceeding- -> Minimal setup to use Gerrit.
  2. How to setup & submit for recurent contributes
  3. How to submit patches one time
Here we will setup clones, outside of the build tree. See faq for commit testing.
This mean you do not need build environement to contribute

Important: for projects using Gerrit, Github pull request will never be merged! This also mean you do not need to create a Github fork for every changed projects

So firstly, I'll explain few terms that are important for you to learn before going towards a bit tricky side.

  1. Git - To be precise, git is a code-sharing website/software that allows you to share your project resources you can 'Make Software, better, together'(That's what the tag line says )!

    Now, before I go to gerrit, read this: Major Open Source Projects, like, CyanogenMod, AOKP, OmniROM etc. don't directly accept pull requests and in case you want to make a change in their source for a fix/feature or anything, you need to send them patches over gerrit which are then reviewed by the trusted members of the community and if they find it valuable enough, gets merged into the git repository!
  2. Gerrit(Copying the definition from Wiki) - Gerrit is a free, web-based team software code review tool. Software developers in a team can review each other's modifications on their source code using a Web browser and approve or reject those changes. It integrates closely with Git, a distributed version control system.
    So, now, git and gerrit are so closely related, that a patch verified over gerrit can directly be merged on git without much hassel, also please note that your gerrit and git username must be same.
  3. Pull Requests - Pull requests are sent over Git after you fork a repository, make some changes into it and then want the owner to merge those changes into his repository, and that's how community development and Open Source works.
  4. Patches - In simple terms, any changes you make to repos of Open Source Projects like LineageOS, OmniRom or AOKP and send them over gerrit for code review are called Patches.
    You can find the Gerrit URL of the project you are working on, on the contribute webpage of the project. Example: OmniRom gerrit is https://gerrit.omnirom.org/ , LineageOS is https://review.lineageos.org/

How GERRIT works?!

Now, Gerrit is deployed in place of this central repository and adds an additional concept, a store of pending changes. Everyone still fetches from the authoritative repository but instead of pushing back to it, they push to this pending changes location. A change can only be submitted into the authoritative repository and become an accepted part of the project once the change has been reviewed and approved.
I found a nice diagram explaining this over the internet that will clear your doubts(if any ) -



There is two different way to use gerrit:
  1. With git , on your computer (useful for recurrent contribute)
  2. Using the Gerrit WebUI (useful for punctual contribute)

Now few important stuff needs to be setup before proceeding-

Install up Git:
Debian/Ubuntu:
Code:
sudo apt-get install git
Fedora:
Code:
yum install git
ArchLinux:
Code:
pacman -S git
openSUSE:
Code:
zypper install git


Configuring git:
This step is very very important as those ID will be the one which identify you and you cannot change them later!
WARNING: You need to setup the same email as on github.com !
WARNING: email is case sensitive!
(For username I highly recommend to use the same as on your computer, but you could use any username you want)
Code:
git config --global user.email "your-email@domain.com"
Code:
git config --global user.name "your-username"


Setting up SSH Keys(Skip this if you have already set them up) -
Code:
ssh-keygen -t rsa -C "your-email@domain.com"
ssh-keygen
Now this will create 2 files in ~/.ssh directory as follows:
ll ~/.ssh
Adding SSH Keys to your Account :
Code:
cat /home/username_on_pc/.ssh/id_rsa.pub
This will show up few lines over terminal, copy those and add them into your Gerrit profile (Will not be detailed, there is a lot of guides on internet for this part)
cat ~/.ssh/id_rsa.pub
Gerrit ssh key setting
Important: you need to setup your username into gerrit UI, otherwise you will never be able to push changes (on the screenshot there is no option to modify username as it is already setup but you should see one):
gerrit username setup
Test ssh is correctly working :
Code:
ssh -p 29418 <username>@<gerrit address>
If you see this message, then everything is setup and ready to propose changes :
ssh test
If you get any errors, reread the howto to ensure you are not missing something.
You can also contact your team (there is probably an IRC channel for this) and ask for help.

Setting up the hook Change-ID :
WARNING: this need to be done in every repository or upload will fail!
Code:
gitdir=$(git rev-parse --git-dir); scp -p -P 29418 <username>@<gerrit address>:hooks/commit-msg ${gitdir}/hooks/
gerrit hook
Attached Thumbnails
Click image for larger version

Name:	cat ssh pub.png
Views:	62
Size:	23.7 KB
ID:	4363077   Click image for larger version

Name:	gerrit ssh keys.png
Views:	56
Size:	94.0 KB
ID:	4363078   Click image for larger version

Name:	sshkeygen.png
Views:	56
Size:	18.0 KB
ID:	4363089   Click image for larger version

Name:	idrsa.png
Views:	64
Size:	6.5 KB
ID:	4363090   Click image for larger version

Name:	gerritusername.png
Views:	46
Size:	31.0 KB
ID:	4363097   Click image for larger version

Name:	sshTest.png
Views:	44
Size:	16.0 KB
ID:	4363166   Click image for larger version

Name:	gerritHook.png
Views:	42
Size:	12.3 KB
ID:	4363186  
The Following 3 Users Say Thank You to nailyk For This Useful Post: [ View ] Gift nailyk Ad-Free
 
 
17th December 2017, 01:44 PM |#2  
nailyk's Avatar
OP Senior Member
Thanks Meter: 2,474
 
More
Making Changes and Submitting Patches -

Way 1. (for recurrent contribute) :

If you have a full build environment setup, the best practice say to not use your build trees for change & submit patches. If you do not have build environment setup, just don't care about this warning

Create a folder (like ~/clones/) where your clones with your changes will reside:
Code:
mkdir ~/clones
cd ~/clones
mkdir ~/clones
Go to git where you would make the change and copy the Clone link:
Code:
https://github.com/omnirom/android_device_sony_shinano-common.git
git clone link
Go back into your terminal and clone the repo (optional: you can specify the branch name with -b <branch name>), then get into clone folder:
git clone shinano
Now you can make the change using your favorite text editor (<escape> then ':q<enter>' to exit vim ):
vim edition
Code:
git status
It tells you what files you modified(In Red color ) and shows on which branch you're currently on.
git status

Now, the committing part,
Run:
Code:
git add -A
Run git status again, and it'll show the files in green color, telling you that the changes have been added.
git status pending
Now:
Code:
git commit -s
This will commit the changes and open up a Text Editor called NANO. Here you need to edit the commit message that appears at the side of the gerrit window to describe what the patch does.
After writing the commit message, press Ctrl+O and then Enter key to save the commit message and then Ctrl+X to exit the editor. This is the committing part done.
git commit -s
Optional (but better ): you can control what your commit changed, then rework if necessary (see last part of the guide):
Code:
git diff HEAD^
git diff HEAD^

Now submitting the patch -
You need to catch the project path from the Gerrit interface. Go into project, list, and find the repository you changed:
gerrit project path
Here the path is android_device_sony_shinano-common. It could include a 'sub-folder' like LineageOS do. For example, same repo on Lineage will be LineageOS/android_device_sony_shinano-common.
WARNING: path is case sensitive.
Go back to your shell and type:
Code:
git push ssh://<username>@<gerrit address>:29418/<repo path> HEAD:refs/for/<branch name>
git push
Attached Thumbnails
Click image for larger version

Name:	mkdirClones.png
Views:	42
Size:	7.6 KB
ID:	4363119   Click image for larger version

Name:	gitClone.png
Views:	32
Size:	29.3 KB
ID:	4363130   Click image for larger version

Name:	gitCloneShinano.png
Views:	40
Size:	27.1 KB
ID:	4363131   Click image for larger version

Name:	vimEdit.png
Views:	36
Size:	10.6 KB
ID:	4363137   Click image for larger version

Name:	gitStatus.png
Views:	50
Size:	17.1 KB
ID:	4363138   Click image for larger version

Name:	gitStatusPending.png
Views:	36
Size:	19.8 KB
ID:	4363140   Click image for larger version

Name:	gitcommit.png
Views:	32
Size:	20.1 KB
ID:	4363148   Click image for larger version

Name:	gitDiffHead.png
Views:	32
Size:	32.2 KB
ID:	4363158   Click image for larger version

Name:	gerritProjectPath.png
Views:	38
Size:	12.2 KB
ID:	4363174   Click image for larger version

Name:	gitPush.png
Views:	42
Size:	34.7 KB
ID:	4363187   Click image for larger version

Name:	gerritReviewer.png
Views:	28
Size:	22.5 KB
ID:	4363195   Click image for larger version

Name:	gerritComment.png
Views:	36
Size:	16.8 KB
ID:	4363196  
The Following 3 Users Say Thank You to nailyk For This Useful Post: [ View ] Gift nailyk Ad-Free
17th December 2017, 01:45 PM |#3  
nailyk's Avatar
OP Senior Member
Thanks Meter: 2,474
 
More
Way 2. (for punctual contribute) :
Log-in into the Gerrit instance you want to commit into. Go into 'Projects', list, then choose the repo you want to make the change in:
gerrit project select
Hit the 'Create Change' button:
Gerrit CreateButton
This open a popup asking for some information:
  • Select branch for new change: the branch you want to commit in,
  • Enter topic for new change: leave empty
  • Description: Enter commit message
Finally hit Create
fillchange
Now your change page is open, you can start editing files with the Edit button on the right:
Gerrit Edit Buton
then Add the file you want change:
Gerrit Add file
The file open in an editor, make the needed changes and save with Save button, then Close:
(Redo the step if you need to change multiples files.)
Gerrit editor
When all your changes are present, hit the Done Editing button to validate your changes.
Gerrit done edit
Your changes are pending and you can display it while clicking on file name:
Gerrit done editing
The changed section is highlighted. If you made a mistake you can use the pencil icon:
Gerrit check edit
Use the button to get back on the summary page.
WARNING: your change is only a draft for now, you need to publish it:
Gerrit publish edit
Attached Thumbnails
Click image for larger version

Name:	GerritCreateButon.png
Views:	40
Size:	20.1 KB
ID:	4363248   Click image for larger version

Name:	GerritCreateChange.png
Views:	36
Size:	14.9 KB
ID:	4363249   Click image for larger version

Name:	gerritEditButton.png
Views:	36
Size:	18.6 KB
ID:	4363257   Click image for larger version

Name:	gerritAddFile.png
Views:	44
Size:	6.1 KB
ID:	4363259   Click image for larger version

Name:	GerritEditor.png
Views:	48
Size:	18.6 KB
ID:	4363261   Click image for larger version

Name:	GerritDoneEdit.png
Views:	38
Size:	6.6 KB
ID:	4363264   Click image for larger version

Name:	gerritDoneEditing.png
Views:	56
Size:	5.3 KB
ID:	4363266   Click image for larger version

Name:	GerritCheckEdit.png
Views:	36
Size:	41.3 KB
ID:	4363272   Click image for larger version

Name:	GerritPublish.png
Views:	42
Size:	4.0 KB
ID:	4363277  
Attached Images
  
The Following 3 Users Say Thank You to nailyk For This Useful Post: [ View ] Gift nailyk Ad-Free
17th December 2017, 01:45 PM |#4  
nailyk's Avatar
OP Senior Member
Thanks Meter: 2,474
 
More
Ask for review :
Once your commit is on Gerrit you need to setup a reviewer. This person will comment, reject or submit your patch.
Hardest part is to find the reviewer. You can ask in the dedicated IRC chan of your rom, or use some tricks like check who merged the commits into the repo.
Once you find who will be the reviewer, add it on the dedicated gerrit field:
Gerrit add reviewer
Once your commit is ok and you want the reviewer take care of it, set-it 'Code-Review +1' and add a comment (will stay on gerrit) about why this change should be merged:
Gerrit review
Guess what?! Done!
Congratulations, you just learned gerrit and know how you use it. I hope you'll send some nice patches and respect the Open Source.

Credits -
Quote:
Originally Posted by v_superuser

> Original kanged thread

The Following 3 Users Say Thank You to nailyk For This Useful Post: [ View ] Gift nailyk Ad-Free
17th December 2017, 04:53 PM |#5  
nailyk's Avatar
OP Senior Member
Thanks Meter: 2,474
 
More
FAQ

Ensure your clone is up to date
Before picking and before writing patch you need to ensure your clone is up-to-date with the remote repository.
Go into the needed folder, then check the remote name:

Here the remote is named 'origin'.
We need to fetch the remote, on the right branch, then switch to that branch:

Code:
git fetch <remote name> <branch>


Code:
git checkout <remote name>/<branch>

(You can notice in my right prompt the current HEAD changed for remote/<remote name>/<branch name> . It is now up to date. )

Warning: Only the checkout command switch your local tree
Warning: git fetch use space between remote name & branch name but git checkout use slash (/) !

How to test pending changes
To test a change pending on Gerrit you need a working build environment for your rom. This guide will not explain how to set it up.
Once you have located the change you want to test,
go into the corresponding folder. Use the project path for hints:

here folder will be device/sony/msm8974-common.

Next use the download button into Gerrit interface

and copy paste the command in your terminal:


If you have merge conflict you will need to solve (with git mergetool, internet search and brain).

Now you can do this step again to merge other commits, or trigger the build for testing.


Update a pending change
You made a commit but notice some problem and it need to be reworked, without creating another one.
You need to follow the Ensure your clone is up to date then How to test pending changes with the commit who need reworking.


Once the commit is fetched locally you can make your changes:


Trigger the amend of the commit:
Code:
git commit --amend


The git editor open and allow you to change the existing commit message:


Once your change is done, upload it:


The commit is updated (new Patch Set) on Gerrit (no new one was created):


Setup Gerrit as remote for easy reuse
Typing the push command each times could be painful if you upload patches often.
You can add Gerrit as a remote for easy reuse:
git remote add <local name> ssh://<username>@<gerrit url>:29418/<repo name>


Now you can simply use git push command:


Warning: need to be done in each repos!
Warning: This tip do not prevent typing HEAD:refs/for/<branch> each time !
Attached Thumbnails
Click image for larger version

Name:	Gerrit-project-path.png
Views:	20
Size:	6.2 KB
ID:	4375685   Click image for larger version

Name:	Gerrit-cherry-pick.png
Views:	24
Size:	46.0 KB
ID:	4375688   Click image for larger version

Name:	Local-cherry-pick.png
Views:	16
Size:	27.1 KB
ID:	4375699   Click image for larger version

Name:	Local-remote-url.png
Views:	16
Size:	15.1 KB
ID:	4375703   Click image for larger version

Name:	Local-git-fetch.png
Views:	30
Size:	13.8 KB
ID:	4375704   Click image for larger version

Name:	Local-git-checkout.png
Views:	20
Size:	25.2 KB
ID:	4375705   Click image for larger version

Name:	Local-all-steps.png
Views:	20
Size:	43.0 KB
ID:	4375711   Click image for larger version

Name:	Local-changes.png
Views:	26
Size:	10.6 KB
ID:	4375717   Click image for larger version

Name:	Local-git-amend.png
Views:	24
Size:	7.3 KB
ID:	4375718   Click image for larger version

Name:	Local-git-amend-editor.png
Views:	18
Size:	31.4 KB
ID:	4375719   Click image for larger version

Name:	local-git-push-amend.png
Views:	16
Size:	32.9 KB
ID:	4375724   Click image for larger version

Name:	Gerrit-updates-commit.png
Views:	26
Size:	13.6 KB
ID:	4375726   Click image for larger version

Name:	Local-gerrit-as-a-remote.png
Views:	22
Size:	31.1 KB
ID:	4375738   Click image for larger version

Name:	Local-gerrit-push-as-a-remote.png
Views:	24
Size:	14.0 KB
ID:	4375739  
The Following 2 Users Say Thank You to nailyk For This Useful Post: [ View ] Gift nailyk Ad-Free
31st December 2017, 05:04 PM |#6  
nailyk's Avatar
OP Senior Member
Thanks Meter: 2,474
 
More
reserved
Post Reply Subscribe to Thread

Guest Quick Reply (no urls or BBcode)
Message:
Previous Thread Next Thread
Thread Tools Search this Thread
Search this Thread:

Advanced Search
Display Modes