git-review: a git-based review/testing system
tav
combined code review system and build/test system. It's based around
git and github and is intended to make life a lot simpler for open
source projects. Here are a few links:
* http://gitreview.com/activity?hide_slaves=1
* http://gitreview.com/commits/ampify?failures_only=1
* http://gitreview.com/profile/tav
* http://gitreview.com/build/6001
* http://gitreview.com/review/ampify/tav/gitreview-guide/1
In an ideal world it'd be super simple to contribute to an open source
project — and this is what I've tried to achieve with git-review.
Thanks to it, the process for a random coder to submit a patch can be
as simple as:
* Clone the repository and create a branch for the patch:
$ git checkout -b name-for-the-patch
* Commit the various changes to the local repository and then run:
$ git review submit
Tada!
Behind the scenes this does a bunch of things to help both the
contributor and the project maintainer(s):
* The branch is rebased on top of the latest upstream/master so that
the maintainer(s) can apply the patch as a fast-forward without having
to merge it. Contributors could use this opportunity to squash their
commits if they wanted to.
* The message for the submission is auto-generated from the commit
messages — the contributor is given a chance to edit it but doesn't
have to waste time explaining what their submission is about if
they've already written decent commit messages.
* Automated checks are run if `revhook` files are present in the
repository. These files contain python functions which are run for
matching files in the changeset, e.g. the following checker in
ampify's `revhook` runs `nodelint` on javascript files — helping
ensure code quality.
@checker(include=['*.js'])
def jslint(changelist, files):
"""JSLinting %s failed.\n\n"""
for filename in files:
stdout, stderr, retcode = run('nodelint', filename)
if retcode:
changelist.error(filename, stderr)
* The changes are submitted to the review-server specified in the
repository's `.gitreview/config.yaml` file where it can be reviewed by
others, e.g.
http://gitreview.com/review/ampify/tav/gitreview-guide/1
* Also, based on which files changed and the repository's
`.gitreview/watchlist.yaml` file, specific individuals are
automatically "cc'ed" for the review, so that as a contributor you
don't have to spend time worrying about contacting the appropriate
individual.
* The review will pop up the next time a cc'ed individual logs onto
the review-server. Here they can see what changed, add comments using
markdown (including in-line ones) and if the code isn't going to do
anything malicious, approve it as "safe to build" by one of the
git-slaves. Of course, if the submission is by one of the core
developers as specified on the repo page, e.g.
http://gitreview.com/repo/ampify all submissions by them are
automatically assumed to be safe to build.
* A machine running `git-slave` will then query the review-server and
generate a new build and run the build phases/tests as specified in
the repository's `.gitreview/config.yaml` before submitting the
results back to the review-server. Setting up new slaves is fairly
easy too:
* Clone the gitreview version of the repository, e.g.
http://github.com/gitreview/ampify
* Create a slave on the review-server, e.g. http://gitreview.com/slaves
* Get the project maintainer to approve your slave for the
particular project
* Set the slave id and token using `git config`
* Run `git slave run` inside the repo — or use `git slave start`
to run it as a daemon
* Failure in any of the build phases, as detected by exit codes, is
also accompanied by the full stdout/stderr streams so as to help debug
the problem, e.g.
http://gitreview.com/build/15001
* Based on the feedback and build results, a contributor can submit
further changes by just running `git review submit` again in the same
branch. This results in an incremented patch number for the review id,
e.g.
http://gitreview.com/review/ampify/tav/gitreview-guide/2
* And once the changes look good, one of the core developers for the
project can give a LGTM (looks good to me) comment which will mark the
review as approved. Alternatively, they can also reject it.
* Anyone can apply a review changeset at any time by simply running
`git review apply <review-id>`. The "review id" is composed of
<submitter's-github-username>/<patch-name>/<patch-number>, e.g.
$ git apply tav/gitreview-guide/2
* A project maintainer can also inform the review-server that a patch
has been applied to upstream/master by running apply with the
--official parameter, e.g.
$ git apply tav/gitreview-guide/2 --official
Similar to reviews, git-slaves also run builds for all commits on the
upstream/master branch. These can be viewed in the /commits view. When
a repository is specified, the commits view includes individual
pass/fail fields for each of the build platforms specified by the
project, otherwise it will only display a single condensed pass/fail —
as different projects may define different platforms for their
git-slaves, e.g.
http://gitreview.com/commits
http://gitreview.com/commits/ampify
Both `git-review` and `git-slave` support intelligent command-line
bash completion so as to make life even easier and here are the
.gitreview config files used by the ampify project:
http://github.com/tav/ampify/raw/master/.gitreview/config.yaml
http://github.com/tav/ampify/raw/master/.gitreview/watchlist.yaml
http://github.com/tav/ampify/raw/master/revhook
http://github.com/tav/ampify/raw/master/src/amp/revhook
The code for `git-review`, `git-slave` and the `review-server` can be
found in the ampify repository:
http://github.com/tav/ampify/tree/master/environ/
It's all public domain as usual. The `review-server` has been written
in a combination of tornado and app engine. It's also integrated with
redis, but I haven't bothered to write a proper cache mechanism yet or
packaged it all up nicely either.
The git review system incorporates elements from various other
projects that I've found to be quite nice — the rietveld code review
system by Guido, the practices as used by the chromium project,
buildbot, etc.
I've focussed on just the functionality — so haven't spent any time
making the review-server app pretty. But it should be fairly usable?
Do let me know what you think. Thanks!
--
love, tav
plex:espians/tav | t...@espians.com | +44 (0) 7809 569 369
http://tav.espians.com | http://twitter.com/tav | skype:tavespian