wiki:org/teams/MetricsTeam/ContributorGuide

Contributor Guide

This document provides helpful information for those who like to start hacking on Metrics products.

Patch Format

Code patches should comply to Metrics Team's Java Style Guide.

Git commit messages should generally follow these commit guidelines, that is, start with a summary of no more than 50 characters, a blank line, and one or more paragraphs with no more than 72 characters per line.

Once you completed a patch, format your patch using git format-patch if you want to submit just a single, small commit. If you want to submit more than one commit, push your changes to a public Git repository somewhere that can be pulled from.

Useful Tools

Here we list some tools we use for making development easier. Using them is not necessary for contribution.

Vagrant

Quite a few Metrics products have their own server setup, environment, and data structure - take a look at Onionoo or CollecTor to just name two.

So, for troubleshooting it can be useful to have virtual machines around that simulate the server. One tool to make virtual machine maintenance easier is Vagrant.

Attached are descriptions for a Vagrant Onionoo setup as example. Please be aware that the referenced vm-file from puppetlabs has not been verified by us, i.e. use at your own risk.

Vagrant for Onionoo Example

Vagrant-based development environment

Before using Vagrant, make sure that Onionoo builds correctly on the host system. This may require running git submodule init && git submodule update, as well as providing all required libraries.

The given Vagrant file uses Version 2, i.e., a Vagrant installation of version 1.1 or above is necessary. The following was tested using 1.4.3 and VirtualBox 4.3.14. (Wheezy stable only provides 1.0.3, Jessie provides 1.4.3)

Local changes to the Vagrantfile: Tell Vagrant how much memory the virtual machine may use, i.e., change

vb.memory = 4096

to some value that makes sense on your machine. Rule of thumb: less than half the RAM, but as much as you want to spare.

Create a Debian Wheezy 64 bit instance:

vagrant up

This command downloads the virtual machine imagine, unless it has been downloaded before, creates a new virtual machine, and runs the bootstrap script in vagrant/bootstrap.sh, if you created the vagrant folder and downloaded the attached bootstrap.sh into it. This may take a few minutes, because the script downloads the virtual machine.

Once this is all done, log into the virtual machine and change to the Onionoo working directory:

vagrant ssh
cd /srv/onionoo.torproject.org/onionoo/

Important: better avoid running Ant in the /vagrant/ directory (which is shared with the host), or the guest system will write directly to the host system, which performs not really well.

Read the INSTALL file and make the appropriate changes to adapt everything to your setup, e.g., memory settings.

Last modified 16 months ago Last modified on Aug 2, 2016, 6:44:02 PM

Attachments (2)

Download all attachments as: .zip