= Contributor Guide
This document provides helpful information for those who like to start hacking on Metrics products.
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
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:
This command downloads the virtual machine imagine, unless it has been
downloaded before, creates a new virtual machine, and runs the bootstrap
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.