Status update + pre-reqs and build instructions.

Change-Id: Ifa1cd5230d31b26e8134534a06d064bb2e6822d7

README.md

diff --git a/README.md b/README.md
index 2eeec0c..7d7f6bb 100644
--- a/README.md
+++ b/README.md
@@ -1,22 +1,56 @@
 GitHub plugin
 =============
+This plugin allows existing GitHub repositories to be integrated
+as Gerrit projects.
 
-Integration between Gerrit and an external repository on GitHub.
+Why using GitHub and Gerrit together ?
+--------------------------------------
+
+Many people see Gerrit and GitHub as opposites: the pull-request
+model adopted by GitHub is often used as "easy shortcut" to the
+more comprehensive and structured code-review process in Gerrit.
+
+There are many discussion threads on this:
+- http://programmers.stackexchange.com/questions/173262/gerrit-code-review-or-githubs-fork-and-pull-model
+- http://stackoverflow.com/questions/2451644/gerrit-with-github
+- http://julien.danjou.info/blog/2013/rant-about-github-pull-request-workflow-implementation
+
+In reality there are already OpenSource projects that have started
+using the two tools together:
+- OpenStack (https://wiki.openstack.org/wiki/GerritJenkinsGithub)
+- MediaWiki (http://www.mediawiki.org/wiki/Gerrit)
+
+The reason for using GitHub and Gerrit together are:
+a) GitHub is widely recognised and accessible by lots of world-wide sites.
+b) Using a public GitHub repo allows to "off-load" a lot of git pull traffic.
+c) Pull-request allows novice users to start getting involved.
+d) Gerrit code-review define the quality gates for avoiding "noise" of unstructured
+   contributions.
+
+Why a Gerrit plugin ?
+---------------------
+
+When using GitHub and Gerrit together, the "master of truth" has to be
+Gerrit: this is because it is the place where more control in terms of
+security and workflow can be defined.
+
+A Gerrit plugin can help controlling the GitHub replica and importing
+the pull requests as Gerrit changes.
+
 
 Integration points
 ------------------
 
-Provides the basic integration points for working effectively
-with Gerrit as code-review tool for an existing repository hosted
-on GitHub:
-
-1. Authentication. (WIP)
+### Authentication. (DONE - Change-Id: I7291a90014e51316af3cb07fd03785c1ef33acd0)
 
 Users can login to Gerrit using the same username and credentials
-in GitHub. Gerrit login points to GitHub for generating the SSO token
+in GitHub. Gerrit login points to GitHub for generating the OAuth token
 to be used for the code-review authenticated session.
 
-2. Push-Pull replication. (TODO)
+The initial Gerrit registration page can be customised to import
+GitHub SSH Keys directly into Gerrit.
+
+### Push-Pull replication. (WIP - Change-Id: I596b2e80b4d9519668a1ab289d6c950139d6a922)
 
 Existing GitHub repositories are automatically replicated to Gerrit
 for the purpose of performing code-review and pushing back changes
@@ -24,7 +58,64 @@
 supports as well the ability to pull branches from remote GitHub
 repositories.
 
-3. Pull-request to Change. (TODO)
+### Pull-request to Change. (TODO)
 
 Hooks into the GitHub pull-request mechanism to automatically create
 a Change in Gerrit submitted for review.
+
+How to build this plugin
+------------------------
+
+### Gerrit 2.8 build
+
+GitHub plugin is designed to work with Gerrit 2.8 (currently in development).
+In order to build the GitHub plugin you need to have a working Gerrit 2.8
+build in place.
+
+See https://gerrit-review.googlesource.com/Documentation/dev-buck.html for a
+reference on how to build Gerrit 2.8 (master branch) using BUCK.
+
+### GitHub API
+
+In order to access GitHub API, we have used the lucamilanesio fork of Kohsuke API 
+layer hosted on GitHub at https://github.com/lucamilanesio/github-api.
+
+You need to clone and build the GitHub API as pre-requisite for building the
+GitHub plugin for Gerrit.
+
+Example:
+  git clone https://github.com/lucamilanesio/github-api.git
+  cd github-api
+  mvn install
+
+### singleusergroup plugin
+
+You need to clone, build and install the singleusergroup plugin for Gerrit
+(see https://gerrit-review.googlesource.com/#/admin/projects/plugins/singleusergroup).
+
+This plugin is needed to allow Gerrit to use individual users as Groups for being
+used in Gerrit ACLs.
+
+Example:
+  git clone https://gerrit.googlesource.com/plugins/singleusergroup
+  cd singleusergroup
+  mvn install
+  cp target/singleusergroup-*.jar $GERRIT_SITE/plugins/.
+
+### Building GitHub integration for Gerrit
+
+Just clone the Git repository (see https://gerrit-review.googlesource.com/#/admin/projects/plugins/github)
+and do a `mvn install` from the root directory.
+This will create two JARs under github-oauth/target and github-plugin/target: the oauth is a JAR library
+to be copied to $GERRIT_SITE/lib whilst the plugin JAR has to be installed as usual under $GERRIT_SITE/plugins.
+
+Example:
+  git clone https://gerrit.googlesource.com/plugins/github
+  cd github
+  mvn install
+  cp target/github-oauth/target/github-oauth-*.jar $GERRIT_SITE/lib
+  cp target/github-plugin/target/github-plugin-*.jar $GERRIT_SITE/plugins
+
+
+
+