The wiki is being retired!
Documentation is now handled by the same processes we use for code: Add something to the Documentation/ directory in the coreboot repo, and it will be rendered to https://doc.coreboot.org/. Contributions welcome!
As part of our move to gerrit, git was introduced as primary SCM.
Register with gerrit
For authenticated access (to submit patches) you'll need a gerrit account which you can register at http://review.coreboot.org/. You also need to add your ssh keys (which are used for authenticating your connections to the repo) and your email addresses (used to match up signed-off-by: statements) to your gerrit user data at http://review.coreboot.org/#settings
It seems that gerrit is picky about the OpenID format. Always provide a full URL, including protocol (ie. http:// or https:// prefix). Unfortunately its error message is non-intuitive.
Gerrit interprets commits as individual changes. These are be autobuilt by Jenkins, and can be reviewed by developers. Once they get a positive review and have no build issues, they can be merged to the master branch. Thus, no developer directly pushes to master.
Reviews grant points on a scale from -2 to 2. The meaning is:
- -2: Do not merge (blocks gerrit from merging)
- -1: I'd prefer you don't merge it
- 0: neutral
- +1: Looks good, but I won't make the last call on it
- +2: Looks good, go ahead and merge (gerrit provides a "submit" function once it has a +2 vote)
-2 and +2 are only available to core developers as it's comparable to commit rights in SVN.
Gerrit and CLI
Reviews normally happens through the website.
Since gerrit exposes an interface through its ssh daemon, it's also possible to do reviews from CLI or mail. Unfortunately there doesn't seem to be any standing tradition on how to build a workflow around these parts, so we'll document our best practices here once they settled.
Gerrit and Email
Gerrit has poor email integration (in fact, it doesn't really have any at all). We send a couple of notifications to the mailing list, but that is a coreboot specific extension. Peter intends to build a mail-to-gerrit gateway should the need arise.
This gateway will provide:
- no patch submission mechanism ("git push" is CLI friendly)
- patch review (maybe openpgp signed "Acked-by" mails)
- patch submission (automatically with Acked-by?)
- maybe patch rejection? (openpgp signed "Nacked-by" mails)
Anonymous read access
Read-only access is available anonymously:
git clone http://review.coreboot.org/p/coreboot
Authenticated read/write access
git clone ssh://<username>@review.coreboot.org:29418/coreboot
Inside the checkout you should install the commit-msg hook which prepares commit messages to fit the style required by gerrit. This needs to happen only once per clone and can be done with
wget -O .git/hooks/commit-msg http://review.coreboot.org/tools/hooks/commit-msg
When you committed your changes locally, you can push them to the server using
git push origin HEAD:refs/for/master
This will create a review request per commit on gerrit.
For automating some aspects of patch submission (ie. simplify the command line), see the last paragraph of http://review.coreboot.org/Documentation/user-upload.html#push_create
There is no code browser that's properly synced with our gerrit instance at this time. This is a work in progress.