Linaro Gerrit Howto
This is Linaro Gerrit services documentation/instructions, written in the form of how-to. Originally written for http://android-review.linaro.org/, it applies to other Gerrit hosts too (but see also Platform/Systems/CodeReviewServer). This page is not intended to replace or duplicate official Gerrit documentation, which can be accessed by following "Documentation" link on each Gerrit host, e.g. https://review.linaro.org/Documentation/index.html (this method to access documentation is recommended, as you will get documentation for the exact Gerrit versions installed). There're more implementation notes at GerritNotes.
More upstream references:
- Normal Development Workflow Actions
- Administrative Configuration and Actions
Gerrit Peculiarities and Things to Know
- Gerrit evolves
- Gerrit's +1's are not additive
- Unobvious terminology for submit and merge actions
- Diff viewing is done file by file and each file opens in a new window
- Per-line comments are not recorded immediately
- Interface is split between Web UI and SSH UI in unobvious way
- Glob-style refs pattern for ACL must end in "/*"
- Regex-style refs patterns for ACL are broken in Gerrit 2.2.1
- 2 accounts with same name/email make unable to select either account
1. Normal Development Workflow Actions
1.1. Creating Gerrit Account
Gerrit instances are now fully integrated with Linaro Single Sign-On, so just logging in to Gerrit with a Linaro email address/password is enough to set up a ready-to-use account. Some steps listed below may still be useful for diagnostics and troubleshooting.
- Click "Sign In"
- Enter your Linaro email address and password
- You SSH username should be set automatically. To verify, click "Settings" and select "Profile". Check the "Username" field (once set, it cannot be changed).
- Your SSH public key(s) also should be synced automatically from Linaro Login settings page (as well as future updated to them). There may be some delay with syncing (less than half an hour). You may want to verify keys some time after initial login by clicking "Settings" in the upper right-hand corner. Then click on "SSH Public Keys".
- Let the repo tool know your SSH username by executing:
git config --global review.android-review.linaro.org.username <GERRIT_USERNAME>
- Verify that you can access Gerrit by SSH:
$ ssh <GERRIT_USERNAME>@android-review.linaro.org -p 29418 gerrit versionYou'll see this if the command executed successfully:
gerrit version 2.x.x
1.2. Setting up your environment for submitting
Before you start submitting code, it is preferable and highly recommended that you add a "commit-msg" file to your ".git/hooks" directory in order to generated a "Change-Id" automatically.
$ wget http://android-review.linaro.org/tools/hooks/commit-msg --2011-08-31 15:18:03-- http://android-review.linaro.org/tools/hooks/commit-msg Resolving android-review.linaro.org... 18.104.22.168 Connecting to android-review.linaro.org|22.214.171.124|:80... connected. HTTP request sent, awaiting response... 200 OK Length: 2329 (2.3K) [application/octet-stream] Saving to: `commit-msg.3' 100%[===========================================================================================>] 2,329 --.-K/s in 0s 2011-08-31 15:18:03 (143 MB/s) - `commit-msg.3' saved [2329/2329] $ mv commit-msg /path/yourproject/.git/hooks/ $ chmod 755 /path/yourproject/.git/hooks/commit-msg
You should also have a good ~/.gitconfig. Something like:
[color] ui = auto [user] name = Zach Pfeffer email = firstname.lastname@example.org [sendemail] smtpencryption = tls smtpserver = smtp.gmail.com smtpuser = email@example.com smtpserverport = 587 cc = firstname.lastname@example.org [review "android-review.linaro.org"] username = zach.pfeffer
...but with your values should work.
1.3. Submit changes for review - repo tool
The easiest way to submit changes for review is by using repo. The process is:
- Go to a directory of component you want to change
- Create a new local topic branch:
repo start my-cool-feature .Note the dot, it means the current project. Alternatively, you can specify explicit project path from the top directory of the Android tree.
- TODO: Discuss Change-Id setup here.
- Make your changes and commit them, following rule of thumb that each commit should deal with one feature-change, be reasonably simple, but at the same time self-containing. Each commit will become a separate change review in Gerrit. Mind the commit message, it should provide all needed information both for review and for understanding the change by looking thru the project history.
- Once all needed changes are committed, submit them to Gerrit with:
repo uploadAs output of that command, URL of a change review in Gerrit will be provided.
1.4. Submit changes for review - git-review tool
This is a recommended way if you don't use "repo" tool. See Platform/Systems/CodeReviewServer#Pushing_Changes_for_Review for details.
1.5. Submit changes for review - raw git
Sometimes, changes to a standalone git repository need to be reviewed. Good example is some repo manifest repository, which itself is managed with raw git.
- Clone/go to existing checkout.
- Check out branch you want to make change against:
git checkout linaro_android_6.0.1
- Create local topic branch:
git checkout -b my-change
- Make changes and commit them following the commit guidelines above.
- Once ready, push change for the review:
git push ssh://<GERRIT_USERNAME>@android-review.linaro.org:29418/platform/manifest.git HEAD:refs/for/linaro_android_6.0.1
Note that it's important to correctly specify target branch in refs/for/... construct. Change URL will be provided as output of the command.
1.6. Submit changes for review - known git
Ex. modify device.mk and push changes Add test scripts to device.mk file
- Clone the git
git clone git://android-git.linaro.org/device/linaro/vexpress_rtsm.git
- enter in to project folder
- choose and checkout the branch
git branch -a git checkout linaro-jb
- modify/change required files which you are interested
- make sure that you have right commit-msg
$ wget http://android-review.linaro.org/tools/hooks/commit-msg $ mv commit-msg .git/hooks/ $ chmod 755 .git/hooks/commit-msg
- commit and push to right project and right branch. if you are not sure ask #linaro-android
git commit -as git push ssh://<GERRIT_USERNAME>@android-review.linaro.org:29418/device/linaro/vexpress_rtsm HEAD:refs/for/linaro-jb
1.7. Managing a review
A change review has URL like http://android-review.linaro.org/#change,12 . On this page, submitter may add specific reviewers which should review the patch (they will receive email), but any registered user can add comments also. Review system is vote-based, a change should get +2 to be accepted (note that it's not enough to get two +1's for this). Exact vote weight depends on project (component) configuration and group membership of the reviewer.
It's possible to abandon a change, or manually set it as merged. The latter is not required though, Gerrit will notice that itself. Actually, so far it seems that Gerrit is too unpicky regarding where change is committed, and will mark a change as merged on it just going to any branch in the repository, for example on pushing local topic branch to the main repository. So, don't do that for now, while it's being figured out ;-). Instead, it's possible to "download" change for other parties to try, see below.
1.8. Testing somebody else's change
Change's page in Gerrit contains number of sample commands which may be used to fetch a change into the local checkout for peers to test. With repo, it's even easier:
cd <project> repo download <project> <change>
TODO: Try different downloads and elaborate on these instructions.
1.9. Merging a change
Once a change has passed thru review and testing, and, approved with sufficient score (+2), and verified (+1) it can be merged. If you're in Approvers group (see below), you will see button "Submit Patch Set N" on the change review page. N is a version of the change (latest is shown by default, as that's apparently what you want to merge most of the time).
You may also want to Use a patchset file to pull in the change without merging it on a branch.
2. Administrative Configuration and Actions
Most actions described here require Administrators group membership.
2.1. Group Setup
To remind, all permissions in Gerrit are assigned on group level. Groups may recursively include other groups, which allows for flexible and structured membership vs permission management of which we take advantage.
Group "Linaro Android Team". This group serves purely enumeration purpose and contains every member of Android team, please members of other teams who work on Android codebase (Landing Teams, Infrastructure, etc.) This group should not be assigned any permission directly. Instead, it is included in other groups which feature specific permission sets. This way, it's easy to add/remove team members and make sure they automatically get all the permission other members have, and at the same time to add/remove some permissions for entire team without affecting other permissions.
Group "Legacy Workflow". Members of this group may push commits directly to branches (effectively bypassing code review) and create new branches (which in general is administrative action in Gerrit). This groups is set up to emulate workflow of standard ssh-based git server has and intended to be used during transitional period until workflow based on mandatory code review is set up. Membership includes "Linaro Android Team".
Group "Approvers". Members of this group can give review score in range -2..+2 and "verified" score -1..+1, i.e. have powers to approve change for merge or veto it. Membership includes "Linaro Android Team".
Group "Change Mergers". Members of this group may merge ("submit" in Gerrit's terminology) (approved) changes into the intended branch. This is performed by "Submit Patch Set N" button which will be shown for this group members on each change page. Please note that the button appears regardless if change was actually approved and verified, so it's member's responsibility to ensure this is the case before merging. Membership includes "Linaro Android Team".
Group "Importers". Members of this group may import (and sync) existing codebases into Gerrit, bypassing most of checks and restrictions Gerrit enforces for normal development workflow. Members include Paul Sokolovsky.
Group "Administrators". Members of this group may review and change Gerrit configuration as well as perform other administrative actions. Note that members of this group don't implicitly get any other permissions (i.e. it doesn't act as "root" user) - instead, they should be added as members of corresponding groups. In other words, Developer and Administrator has the same permissions as just Developer regarding the code changes (unless Administrator group was given extra permission which is bad practice). Members include Bernhard Rosenkraenzer, Yongqin Liu, Paul Sokolovsky.
2.2. Create and delete a project
Project (and associated repository) creation is performed via SSH interface. Project deletion is not supported, so think twice about a name, make sure you select good "path" (like, all kernels start with "kernel/", external ARM-native software with "platform/external/", while ART software with "platform/packages/apps/", etc.)
ssh -p 29418 android-review.linaro.org gerrit create-project kernel/imx53
2.3. Importing repository
First create a corresponding project (take chance to clean up the naming). To perform import, a user must be in "Importers" group (suggested temporary membership just for the time of import). SSH into git.linaro.org, cd into repository dir, and run:
git push ssh://<GERRIT_USERNAME>@android-review.linaro.org:29418/kernel/imx53.git 'refs/heads/*' 'refs/tags/*'
Once imported, you should think about exit strategy for the old repository - it's confusing to have two copies lying around. For example, if you have access, rename old repository to be easily recognizable as old, and to be deleted after some time. If you don't have access, submit RT ticket for that to be done.
(This is "optimized" way, which doesn't involve additional checkout elsewhere. But you can import from a local copy, just take care to import all branches/tags, verify all is there.)
2.4. Create and delete a branch
It's possible to give "Push branch" permission to normal users so they were able to create and push branches via git command line. If it is "Push branch" with "Force Push" option, users also will be able to force-push commits involving history rewriting and delete branches.
However, in normal Gerrit workflow branch creation is administrative action performed as follows: Admin -> Projects -> <project> -> Branches. It is accessible to Project Owner group and Administrators.
To create a new branch, enter initial revision for branch (usually name of another branch). Remember, branches in git are always created from some revision! If you don't specify one, Gerrit will create a branch from master and that's rarely correct in Lianro setup (where master belongs to upstream). If you made a mistake and created a branch with wrong base, delete it immediately and re-create again.
To delete a branch, follow steps in previous paragraph to access Branches menu for a project and use checkboxes and Delete button.
2.5. List registered users
ssh <GERRIT_USERNAME>@android-review.linaro.org -p 29418 gerrit gsql gerrit> select full_name, preferred_email from accounts;
2.6. Linaro Gerrit support utilities
There's linaro-android-gerrit-support project and associated BZR repository hosts utilities used for initial Gerrit migration, maintaining, and upstream syncing. Please note that these are special-purpose utilities, and may be rough in their interface and error handling.
2.7. Upstream sync
Linaro AOSP tree is a proper superset of AOSP tree. That means that it has all content from AOSP, plus also Linaro changes and developments. It is also automatically syncs with upstream to ensure constraint above holds true. For the automatic syncing to work, branch policy should be strictly adhere too, specifically no commits should ever go into any upstream branch ("master" in particular).
Syncing is performed by sync-aosp.sh script from linaro-android-gerrit-support, which is wrapper around gerrit-mirror.py tool, which in turn requires proper configuration in config.py.
sync-aosp.sh syncs only components already present in the mirror (and Linaro Android tree). To pull in new upstream components, following two actions should be executed from time to time manually:
- Create new projects in Linaro Gerrit:
python gerrit-mirror.py upstream-create
- Clone new projects into mirror:
cd $MIRROR_ROOT python /path/to/linaro-android-gerrit-support/gerrit-mirror.py clone git://android.googlesource.com gerrit://upstream
2.8. Manual mirroring and syncing upstream project
(Temporary, until AOSP mirror will be fully deployed and extended to other upstreams.)
Initial mirror create:
cd /mnt/gerrit-mirror mkdir -p git.omapzoom.org/kernel cd git.omapzoom.org/kernel/ git clone --mirror git://git.omapzoom.org/kernel/omap.git cd omap.git git push ssh://email@example.com:29418/kernel/omap-omapzoom.git 'refs/heads/*' 'refs/tags/*'
Syncing it (at regular intervals):
cd /mnt/gerrit-mirror/git.omapzoom.org/kernel/omap.git git fetch git push ssh://firstname.lastname@example.org:29418/kernel/omap-omapzoom.git 'refs/heads/*' 'refs/tags/*'
3. Gerrit Peculiarities and Things to Know
If you didn't use Gerrit before, chances are that some thing will be unexpected or confusing for you, based on experience with other tools. This section tries to smooth user surprise.
3.1. Gerrit evolves
Gerrit evolves with each release, so things you have read on this page, or somewhere else, or knew yourself, may slightly (or not so slightly) change. As mentioned above, the official Gerrit documentation for a particular version is the authoritative reference (don't just google it up and assume it should work like that - please check the version).
3.2. Gerrit's +1's are not additive
Gerrit code review markings are not additive numeric values. For example, two +1's don't make +2. They are rather short labels for semantic approvals like "Looks good, but someone else must approve" or "Approved, I am sure this is OK".
3.3. Unobvious terminology for submit and merge actions
There are two main and distinct actions in Gerrit related to a patch life cycle:
- At first, patch is submitted for review
- Then, it is merged into target branch
One may think that it would be intuitive to call those actions "submit" and "merge", but that's not how it is in Gerrit. In particular, permission for 2nd action is called "Submit", UI button which initiates action 2 is named "Submit Patch Set", however change which have undergone action action 2 is called "Merged".
3.4. Diff viewing is done file by file and each file opens in a new window
When "Diff All Side-by-side" or "Diff All Unified" link is pressed on change page, the patch is split file by file and each file's chunk is opened in a separate browser tab/window. If patch affects many files, that may affect browser's usability. The standard Gerrit workflow for patch review appears to be to click first file's diff link, then navigate between files back and forth by the link at top&bottom.
If you still want to see complete patchset, as in most other tools, you may use "(gitweb)" link to open patch in gitweb. However, it won't be possible to leave per-line comments in this case.
3.5. Per-line comments are not recorded immediately
When adding per-line comments in diff viewer, they are not recorded on the server immediately, but rather cached. To submit them, you should add normal whole-patch comment with "Review" button (which you may leave empty).
3.6. Interface is split between Web UI and SSH UI in unobvious way
You may find that some actions you'd expect to be doable in Web UI are not available there, but available via SSH command line UI instead. For example, when creating project via Web UI (which requires appropriate, usually administrative-level, permission), you can, and sometimes should, set a right parent project. But if you missed with a parent, or want to change it later, that's possible only via SSH.
3.7. Glob-style refs pattern for ACL must end in "/*"
TODO: Re-verify this with current Gerrit version.
When specifying glob-like refs pattern in an ACL rule, a star must be the last character of pattern, and it must be immediately preceded by a slash. That means that with glob-style patterns it's not possible to enforce branching rule like "all local branches must start with 'linaro', e.g. 'linaro_android_6.0.1', 'linaro-master'". Instead, only enforcement for 'linaro/android_6.0.1' and 'linaro/master' would be possible.
3.8. Regex-style refs patterns for ACL are broken in Gerrit 2.2.1
TODO: Re-verify this with current Gerrit version.
Regex-style patterns, e.g. '%refs/heads/linaro.+' are broken in Gerrit 2.2.1 (they are known to work in Gerrit 2.1.x) - they are not accepted by form validator, and even if applied directly to refs/meta/config branch, don't seem to work. List thread. This is expected to be fixed in 2.2.2.
3.9. 2 accounts with same name/email make unable to select either account
If it happens that there're 2 or more accounts, each having the same full name and email (case of only the same full name may be affected too), when trying to select either of accounts via a dropdown box (to add to a group for example) will lead to the error:
Code Review - Unknown User Full Name <email> is not a registered user.
The workaround is to use (type) SSH username (which is enforced to be unique) or numerical account id.
Resolving this issue on DB level (use with care).
Platform/Systems/Gerrit (last modified 2016-05-25 19:44:07)