DEV_README

Gerrit 2 - Developer Notes
--------------------------

You will need to have the GWT (Google Web Toolkit) SDK installed on
your system.  A Java 5 or later SDK is also required to run GWT's
compiler and runtime.

To create a new client workspace:

  mkdir gerrit2
  cd gerrit2
  repo init \
    -u git://android.git.kernel.org/tools/manifest.git \
    -b gerrit2

  echo 'GWT_SDK = path/to/your/gwt' >gwtjsonrpc/config.mak
  echo 'GWT_SDK = path/to/your/gwt' >gerrit/config.mak


Setting up the Database
-----------------------

You'll need to configure your development workspace to use a database
gwtorm supports (or add the necessary dialect support to gwtorm,
and then configure your workspace anyway).

  cd webapp/src
  cp GerritServer.properties_example GerritServer.properties

Now edit GerritServer.properties to uncomment the database you are
going to use, and possibly update properties such as "user" and
"password" to reflect the actual connection information used.

In the future gwtorm (and Gerrit 2) should be getting the DataSource
from the application server, but I don't yet know how to configure
that in GWT hosted mode.


Setting up Eclipse
------------------

Bootstrap the build by compiling the libraries:

  make -C gerrit web-lib

Setup the "GWT" user library (see gerrit/README_ECLIPSE).

Import the 'Gerrit-webapp' project from "gerrit/webapp/".


Debugging the Application
-------------------------

From Eclipse:

  Use the "Gerrit-webapp" launch profile.

From the command line:

  make -C gerrit web-shell


Client-Server RPC
-----------------

The client-server RPC implementation is gwtjsonrpc, not the stock RPC
system that comes with GWT.  This buys us automatic XSRF protection.
It also makes all of the messages readable and writable by any JSON
implementation, facilitating "mashups" and 3rd party clients.

The programming API is virtually identical (you just need to extend
RemoteJsonService instead of RemoteService).


Why GWT?
--------

We like it.  Plus we can write Java code once and run it both in
the browser and on the server side.  This will be very useful as
we implement offline support in Gerrit.


Feature Roadmap
---------------

* Everything Gerrit does today.

  This list is long so I'm not listing it all here.

* Offline Support

  Initially we will use Google Gears, but HTML 5 will include
  standardized offline application support that we should make
  use of.  With GWT we can target both.  The plan is to initially
  target Google Gears, and add HTML 5 support once Gerrit 2 is
  mostly functional and/if at least one major browser supports it.

* Federated Instances

  Gerrit 2 instances should be able to forward changes between
  each other.  This couples with the next item ("No Google") to
  allow corporate contributors to open source projects to use a
  Gerrit 2 server internally to review (and scrub protected IP)
  prior to submitting changes upstream to a public Gerrit server
  and an established open source project.

* No Google Requirement

  Gerrit 2 must not require any Google services to run.  This makes
  it suitable for installation inside of corporate firewalls where
  information security demands certain data stays internal.

* Arbitrary SQL Database

  Gerrit 2 should support any standard SQL database, including
  popular open source (PostgreSQL, MySQL, SQLite) and pure Java
  implementations (H2).  Some commerical servers may wind up being
  supported, but only by virtue of Gerrit 2 sticking to a very small,
  commonly implemented subset of SQL.

  This requirement (and the prior one) means Gerrit 2 won't run on
  Google App Engine, as GAE does not support arbitrary SQL syntax.