Guide to the demo instance of Gerrit and Git
What's all this?
We're planning to migrate to Git some time after the 3.9 3.10 release. We're currently exploring options for how to host the git repository in a way that allows secure access for committers, and we're also looking at options to replace the patch-storage part of Flyspray with a patch tracker/code review system. Gerrit serves both these purposes and is used by some other projects such as Android. A demo instance has been set up so that Rockbox developers (committers or not) can try it out and see what they think. This page instructs you on how to get set up to use the demo instance and some things you may want to try. It is not intended to be a guide to how to use git (though a guide on how to use git for basic stuff on Rockbox will be written at some point), but it tries to explain things as best as it can.
To assuage any fears people might have about this:
- We have not yet decided to use Gerrit (or any code review tool), this is a demo to see how people like it.
- We are not likely to make code review mandatory for committers.
- The permissions and policies configured currently can be changed, nothing is final. Gerrit supports a variety of ways of working.
- We haven't converted the SVN history to Git yet, so the instructions will refer to a repository called "sandbox" which just contains a small number of files/commits for demo purposes.
- A number of people object to the fact that Gerrit is currently configured to refuse merges and forces you to rebase. I'm leaving it like this for now, but it will probably be relaxed such that you can enable the ability to merge for yourself once you are confident you understand Git usage. Forcing rebasing by default makes the workflow more like SVN and prevents unnecessarily complicating history because they made a mistake.
Everyone will want to follow these steps before they start (except for the "read-only copy" scenario below which simply requires that you have git installed).
- Install git, if you don't already have it. You don't need any extra packages (git-svn is not required). If you're on Windows then we're not sure yet whether Cygwin git or msysgit is the preferred option; if you feel like experimenting with this please let us know.
- Set up some basic git settings. If you've used git before you have probably done this already. You must set a real name and email address with
git config --global user.name "John Doe"; git config --global user.email firstname.lastname@example.org so that your changes can be attributed to you. You will probably find git easier to use if you enable coloured terminal output with
git config --global color.ui auto
- Create an SSH key, if you don't already have one. On Linux you can just run
ssh-keygen to do this. Set a passphrase on the key so that it can't be used if the file is stolen from your computer. To avoid you having to type the passphrase repeatedly as you work with the remote repository you probably want to add the key to an ssh key agent; check
man ssh-agent or Google for how to set this up on your distro/environment.
Gerrit account setup
Unless you're only going to try the read-only copy scenario you also need to do this.
- Have some kind of OpenID account. Google accounts, Yahoo accounts, and a bunch of other website accounts provide OpenID. This does not include Twitter/Facebook (it's not OAuth). You can run your own if you think that's a good idea; Gerrit doesn't care where your OpenID comes from.
- Go to http://gerrit.rockbox.org/ and click on the "Register" link in the top right corner. Put in your OpenID URL, or click the google/yahoo buttons if you are using google/yahoo. You'll get sent to your provider's site to confirm that you want to allow this machine to log you in. NOTE: Gerrit requires
http:// at the start of your OpenID, even though this violates the OpenID specification.
- Gerrit will offer you a first time setup page containing several fields you will need to fill in. Please do use your real name/username/etc here because if we do start using Gerrit for real we want to be able to reuse this existing account database so you don't have to set it up again. Enter your full name, choose a username on the server (the username cannot be changed later), and paste your SSH public key into the key field. You can upload multiple keys if you want.
- To test that your SSH account has been set up correctly, run
ssh -p 29418 email@example.com - if everything is OK then you should get a message from gerrit telling you that you have connected successfully, but interactive shells are disabled.
You don't need to follow every section here. Each scenario is a different set of instructions for a different potential use case. Take your pick.
Easily getting a read-only copy of the repository
This is useful if you don't actually intend to contribute back, and just want to look at the code locally or compile your own build without significant modifications. You just have to have git installed; you don't need to do any setup. There are two ways to do it:
- Using the git protocol, which is fast but may be blocked by some firewalls/proxies:
git clone git://git.rockbox.org/sandbox.git (THIS DOES NOT WORK RIGHT NOW - it will be re-enabled later).
- Or, using anonymous HTTP, which may be slower but more firewall-compatible:
git clone http://gerrit.rockbox.org/p/sandbox (note (if you know about git stuff) that this is a smart http server provided by gerrit, not a dumb server, so it is still fairly fast.)
Either way will give you a clone of the repository in a directory
sandbox. This clone contains the full history of the repository, and all normal git commands will work on it; the only thing you can't do is actually push changes from here back to Gerrit (since these protocols are read-only). It is possible to change the configuration of this clone later to change the protocol to one which allows writing, though; you don't need to clone another copy.
Getting a copy of the repository the "normal" way
This is the normal way to do it assuming you want to prepare some changes and put them up for review or commit them. You must have already set up a Gerrit account for this.
- Clone the repository over ssh:
git clone ssh://firstname.lastname@example.org:29418/sandbox.git
- Install Gerrit's commit message hook into your clone of the repository:
cd sandbox; scp -p -P 29418 email@example.com:hooks/commit-msg .git/hooks/
This gives you a clone of the repository in a directory
sandbox. This clone contains the full history of the repository, and all normal git commands will work on it. You can push to Gerrit easily from this clone; Gerrit will be set up as a remote called
origin. The commit message hook is important to make sure that Gerrit can match up successive versions of the same change, and you need to install it separately in each copy of the repository.
Actually making some changes
Once you have a copy of the repository you'll want to make some kind of local change to it. This is not a full set of instructions for using git; refer to a quickstart guide elsewhere if you aren't sure. This does not cover using multiple local branches; everything will be done in branch master.
- Edit/create/delete files as normal.
git status will show you what you have changed, and
git diff will display a diff.
git add to tell git which changes you intend to include in your commit by adding them to the index. This applies to edited files as well as newly created files.
git rm is the equivalent for file deletion.
- Commit your changes locally with
git commit (to commit the contents of the index) or alternatively
git commit -a to commit all changed files regardless of the index status (but new files will still not be committed unless you added them). You'll be prompted for a commit message. The expected format is a one-line summary of the change (a single sentence), then a blank line, then a fuller description. The commit message hook you installed in the setup step will append a Change-Id line to the message you provide.
If you decide to make more changes, there are two different ways to do this: you can either make a second/third/etc commit, in which case they will be treated as separate but dependent changes when uploaded to Gerrit, or you can amend the original commit to include the new changes with
git commit --amend. Amending your commit is preferable in most cases when using Gerrit. When amending, do not remove or change the Change-Id line in the commit message, otherwise Gerrit will not be able to recognise it as a later version of the same change.
Directly committing a change without using code review
On the real repository, only committers will be able to do this; however, the sandbox repository allows all Gerrit users the permissions of committers, so you don't need to ask for permissions to try it. If you aren't currently a committer then this is probably not interesting.
- Make sure you've already committed some local changes.
git push origin HEAD:master to attempt to push your local changes to the server. If successful you have now committed and everyone else will see your change the next time they fetch.
- Otherwise, you may see a message which says "To prevent you from losing history, non-fast-forward updates were rejected". This means that someone else has committed since you cloned the repository, and thus your change is no longer based on the most current code. The current configuration forbids pushing merges, so to update you must do
git pull --rebase which will download the new changes and then rebase your commit(s) on top of the most current version. Do not use a plain
git pull as the error message suggests, as this will create a merge which cannot be submitted.
This is the equivalent of
svn commit, including the requirement that you
svn update before committing.
Submitting a change for code review
This will be allowed for both committers and non-committers; you simply have to create a Gerrit account.
- Make sure you've already committed some local changes.
git push origin HEAD:refs/for/master to push your local change as a new code review. This does not require that your local copy be up to date, so it should not fail. The result will include a HTTP URL which points to the newly created code review.
- Open the URL to see the review. Any Gerrit user can review your change if they choose, but you can also invite people to review the code using the Add Reviewer button if they have a Gerrit account.
- If you decide the change needs to be updated, make sure you amend your existing local commit with
git commit --amend, and then you can simply push it to refs/for/master again. Gerrit will use the Change-Id added by the commit message hook to identify the change and will add it as a new patch set on the same code review, resetting the status of the review.
Reviewing a change
All changes are publicly visible and anyone with a Gerrit account can submit comments, as well as assigning a code review score of +1 or -1. These scores are only advisory and do not affect the workflow. Committers can also assign a score of +2 or -2, which are significant: a change must have at least one +2 review before it can be submitted, and a change may not be submitted if it has any -2 reviews. These scores do not add up: two +1s are not a +2, and a +2 does not cancel out a -2. There is also a second field "Verified" which is intended to represent whether the change has been tested and shown to work - Verified only has +1 and -1, which only committers can assign, and which function like +2/-2 in code review. You can set +1 Verified on your own changes if you have in fact tested them, but you are strongly discouraged from giving your own changes a positive code review score (Gerrit does not actually stop you doing this, however).
For the sandbox repository, all users have committer permissions. The scoring system can be changed if we want.
To actually review a change:
- Write comments on specific lines of the patch, if you want: go into the diff view for a file and double click a line to leave a comment there. These comments will be saved as drafts for now.
- Once you've read all the changes and written any specific comments, you can click the "Review" button on the patch set and you will get a form asking you to assign scores and also add any general comments that do not apply to specific lines/files.
- Click Publish Comments in that form, and the score will be updated and the draft comments published. The comments will get emailed to the owner of the change and also to any previous reviewers.
Comments and scores apply to particular versions of a change (a single patch set) so if the author later uploads a new version all scores are reset. The old comments are still visible if you look on the old patch set.
Committing a change
Once a change has been scored +1 Verified and +2 Code Review, and has no -1 Verified or -2 Code Review scores, it is eligible to be submitted. Anyone with committer rights can do this (on the sandbox repo this is everybody) - it does not have to be the original author, and you do not need to check out their code locally (or do anything locally at all). All you have to do is click "Submit Patch Set x" on the code review, and as long as the score requirements are satisfied it will get submitted immediately. Changes in Git have two identities associated with them: the committer and the author. The original author of the change will be recorded as the author, but the committer will be the Gerrit user who clicked the submit button.
Copyright © by the contributing authors.