Setup: Gerrit

Gerrit publishes official setup instructions on their Developer Setup page, with additional information under Building with Bazel. For CS 5150, you will work on Gerrit in the following way:

Use an internally-hosted Gerrit repository (your team will be given access to one on Cornell’s GitHub server); you will be sharing this repository with other teams adding different capabilities to Gerrit.
Your internal repository was forked from the v3.5.0.1 release to give you a stable foundation. You should follow the compatibility rules for this release (in particular, the oldest version of Java you need to support is 11).
Use upstream versions of submodules (if you think you need to modify code in these repositories, notify the instructor).
Gerrit supports plugins and extensions developed in separate repositories (including core plugins that are included as submodules). If you are developing your feature as a plugin, you may commit it directly to your Gerrit repository for simplicity; if you would prefer a separate repository, talk with the instructor.

Quick start for Linux

Here are some streamlined instructions for getting Gerrit running in a development environment running a Debian-based Linux distribution (tested on Ubuntu 20.04 and Debian Bullseye).

Install required system packages:

sudo apt-get install git curl zip gcc g++ default-jdk-headless python3-minimal

Install bazelisk from https://github.com/bazelbuild/bazelisk/releases (you can do this manually; just be sure that it ends up as an executable named bazel in your $PATH):
```
sudo wget https://github.com/bazelbuild/bazelisk/releases/download/v1.11.0/bazelisk-linux-amd64 -O /usr/local/bin/bazel -q
sudo chmod +x /usr/local/bin/bazel
```
Create a directory to store your code in. This example creates a cs5150 folder in your home directory, but you may store it elsewhere if you wish.
```
mkdir ~/cs5150
```
Clone the course fork of Gerrit, including upstream submodules. Replace gerrit-X with the name of the repository that your team was given access to.
```
cd ~/cs5150
git clone --recursive git@github.coecis.cornell.edu:cs5150-sp22/gerrit-X.git gerrit
```
Build Gerrit. Run this whenever you want to compile your changes to check for compilation errors or to test in a staging deployment. The build product is bazel-bin/gerrit.war.
```
cd ~/cs5150/gerrit
bazel build gerrit
```
Subsequent instructions assume you are running them from your repository root (~/cs5150/gerrit in this example).
Initialize a new server instance. The environment variable $GERRIT_SITE specifies the directory where the instance’s data will be stored and is passed as an argument whenever starting or stopping the server.
```
# Set this variable every time you start work in a new shell
export GERRIT_SITE=~/cs5150/gerrit_testsite

java -jar bazel-bin/gerrit.war init --batch --dev -d "$GERRIT_SITE" --no-auto-start
```
Start your Gerrit server. Rather than invoking $GERRIT_SITE/bin/gerrit.sh, which uses the version of gerrit.war that it was initialized with, this uses the most recently-compiled version.
```
java -jar bazel-bin/gerrit.war daemon -d ${GERRIT_SITE} --console-log --show-stack-trace
```
Visit http://localhost:8080/ in your web browser and you should see Gerrit running. To stop the server, type Ctrl+C in the terminal where you started it.

Testing

The “large” tests take a long time to run, so we recommend sticking with the “small” and “medium” tests for getting rapid feedback on your changes.

bazel test --test_size_filters=small,medium //...

Administration

TODO: creating user accounts, setting up a repository, pushing changes to a review

Style guide

Read the official developer guidelines at Crafting Changes. Gerrit follows the Google Java Style Guide.

Style rules can be enforced automatically by running google-java-format. Install with:

./tools/setup_gjf.sh

The output of this script will tell you how to set up an alias for the tool it installed.

Documentation

Run the following to generate HTML documentation from Markdown files:

bazel build Documentation

Browse the results at bazel-bin/Documentation/index.html. When you document your project, that documentation should be included among these pages.

If you would like to generate Javadoc API documentation, run the following commands:

bazel build //plugins:plugin-api-javadoc
bazel build //java/com/google/gerrit/extensions:extension-api-javadoc
bazel build //java/com/google/gerrit/acceptance:framework-javadoc

The output will be archived in the following ZIP files: bazel-bin/plugins/plugin-api-javadoc.zip, bazel-bin/java/com/google/gerrit/extensions/extension-api-javadoc.zip, bazel-bin/java/com/google/gerrit/acceptance/framework-javadoc.zip.

Virtualization

A good way to avoid headaches during setup and to improve consistency is to use virtualized development environments—virtual machines or containers that are pre-configured for developing, testing, and running a particular project. A popular tool for managing virtual dev environments is Vagrant.

The combination of Java and Bazel make Gerrit highly portable, reducing the need for virtual dev environments. But if you would like some isolation, the following Vagrantfile and provisioning script will build and run Gerrit in a VirtualBox virtual machine while still allowing you to edit the code from your host machine.

Vagrantfile:

Vagrant.configure("2") do |config|
  config.vm.box = "bento/ubuntu-20.04"
  config.vm.provision :shell, path: "vagrant-provision.sh"
  config.vm.network :forwarded_port, guest: 8080, host: 8080

  config.vm.provider "virtualbox" do |v|
    v.memory = 4096
    v.cpus = 4
  end
end

Provisioning script (save as vagrant-provision.sh):

#!/bin/bash
set -e
apt-get update && apt-get install -y git curl zip gcc g++ default-jdk-headless python3-minimal
wget https://github.com/bazelbuild/bazelisk/releases/download/v1.11.0/bazelisk-linux-amd64 -O /usr/local/bin/bazel -q
chmod +x /usr/local/bin/bazel