README: add real docs
Signed-off-by: Dmitry Vyukov <dvyukov@google.com>
Change-Id: I64a50420338a211d823c52d79eb153e4aa7f88db
diff --git a/README.md b/README.md
index 9ecd2b2..78ce917 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,110 @@
-# Testing documentation
+# Gerrit code reviews for Linux kernel
-* Fruit
- * Orange
- * Pear
-* Cake
+`Gerrit` is a modern code review system that supports:
+
+* patch series
+* versioned changes (no need to explain what changed)
+* change tracking (what's your open changes/changes to review)
+* side-by-side diffs (shows added/removed parts within a line)
+* full file context and base repository/revision
+* web-based rebase and editing files/commit message
+* preserving comments across versions
+
+and more. Refer to
+[User Guide](https://gerrit-review.googlesource.com/Documentation/intro-user.html)
+and [Gerrit Docs](https://gerrit-review.googlesource.com/Documentation/index.html)
+for more info, but the information below should be enough to get you started.
+
+The instance consists of a set of mirrors of kernel git repositories,
+which you can see and browse at
+[linux.googlesource.com](https://linux.googlesource.com/). Review changes can
+be created only for the mirrored repos. Currently two dozens of the most
+active repos are mirrored, but this list can be easily extended if there is
+interest.
+
+The second part is the review system at
+[linux-review.googlesource.com](https://linux-review.googlesource.com).
+All uploaded changes are public and visible to everyone, however creating
+own changes and participating in reviews requires a Google account. To sign in
+into the review system, click [Sign in](https://linux-review.googlesource.com)
+link in the top-right corner. Once you signed in you can see your
+outgoing, incoming and CCed changes at the
+[dashboard](https://linux-review.googlesource.com/dashboard/self).
+
+## Tutorial
+
+To create a change for the
+[net](https://linux.googlesource.com/linux/kernel/git/davem/net/)
+tree you need to:
+
+* clone the tree with:
+
+```
+git clone https://linux.googlesource.com/linux/kernel/git/davem/net
+```
+
+or add a new remote with:
+
+```
+git remote add -f gerrit-net https://linux.googlesource.com/linux/kernel/git/davem/net
+```
+
+* Sign in into the gerrit instance using [Sign in](https://linux.googlesource.com)
+link in the top-right corver.
+
+* Click
+[Generate Password](https://accounts.google.com/o/oauth2/auth?response_type=code&access_type=offline&approval_prompt=force&client_id=413937457453.apps.googleusercontent.com&scope=https://www.googleapis.com/auth/gerritcodereview&redirect_uri=https://www.googlesource.com/new-password&state=linux)
+link in the top menu. Copy-paste and execute the script which adds an auth
+cookie for pushing changes for review.
+
+* Add gerrit commit hook to the git repo with:
+
+```
+(f=`git rev-parse --git-dir`/hooks/commit-msg; \
+ mkdir -p $(dirname $f); \
+ curl -Lo $f https://gerrit-review.googlesource.com/tools/hooks/commit-msg; \
+ chmod +x $f)
+```
+
+The hook simply adds `Change-Id: unique-id` to commit messages, gerrit uses
+it to understand uploads of new versions of the same change.
+
+* Commit a change as usual:
+
+```
+git checkout gerrit-net/master
+git checkout -b my-test-gerrit-change
+sed -i "s#mm_init(#mem_init(#g" init/main.c
+git commit -s --all -m "init: test change"
+```
+
+* Push the change for review:
+
+```
+git push gerrit-net HEAD:refs/for/master
+```
+
+Pushing to the special path `refs/for/target-branch` creates a change based
+on the `target-branch`. The command output will contain URL of the change, e.g.:
+
+[https://linux-review.googlesource.com/c/linux/kernel/git/davem/net/+/1109](https://linux-review.googlesource.com/c/linux/kernel/git/davem/net/+/1109)
+
+you should also see it on the
+[dashboard](https://linux-review.googlesource.com/dashboard/self).
+
+* Push a new version:
+
+```
+sed -i "s#mem_init(#mem_initialize(#g" init/main.c
+git commit --amend --all --no-edit
+git push gerrit-net HEAD:refs/for/master
+```
+
+Gerrit knows it's a new version based on the `Change-Id` tag. Now you can see
+the new version at:
+
+https://linux-review.googlesource.com/c/linux/kernel/git/davem/net/+/1109/2
+
+as well as the diff between versions:
+
+https://linux-review.googlesource.com/c/linux/kernel/git/davem/net/+/1109/1..2
