CS 5150: Software Engineering (Spring 2025)

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:

Quick Start

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) or on a macOS system.

  1. Install required system packages:

    Linux:

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

    macOS (install Homebrew if necessary):

    brew install git curl zip gcc python openjdk bazelisk

  2. 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.25.0/bazelisk-linux-amd64 -O /usr/local/bin/bazel -q
sudo chmod +x /usr/local/bin/bazel

    If you’re on a Mac and you installed bazelisk via brew in Step 1, you can skip this step.

  3. 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

  4. Have one team member do this step. First, clone and set up the desired version of Gerrit, including upstream submodules.

    cd ~/cs5150
git clone --recurse-submodules https://gerrit.googlesource.com/gerrit
cd gerrit
git checkout 7b66076406a4a03053139dd19706b212b540719c
(
   cd .git/hooks
   ln -s ../../resources/com/google/gerrit/server/tools/root/hooks/commit-msg
)

    UPDATE You will also need to change the submodule URLs, which are currently specified with a relative path, to a direct URL pointing to the https://gerrit.googlesource.com-hosted repositories. To do this, open .gitmodules and replace all instances of .. with https://gerrit.googlesource.com. Then save and commit these changes.

    Then on the Cornell GitHub, have one group member create a new empty repository, making sure not to initialize the repository with a README. The following steps assume this repository is hosted at https://github.coecis.cornell.edu/blp73/gerrit. You should modify the commands to reflect the URL of your own repository.

    Change the origin remote to this new empty repository and push the current state of the cloned repository.

    git remote set-url origin git@github.coecis.cornell.edu:blp73/gerrit.git
git checkout -b main
git push -u origin main

  5. Once the Cornell-hosted repository is created, all group members can clone this repository.

    cd ~/cs5150
git clone https://github.coecis.cornell.edu/blp73/gerrit

  6. 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

    If you get an error about missing input files from somewhere in node_modules, try running bazel clean --expunge to clear the Bazel cache.

    Subsequent instructions assume you are running them from your repository root (~/cs5150/gerrit in this example).

  7. 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

  8. 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