Contributing to StarCluster

Note

Prerequisites: You need to install git before following these instructions. You should also familiarize yourself with the basic use and work flow model of git before following these instructions. The folks over at github put together a good introduction to git that you can use to get started with git.

Overview

Sign-up for a github account

StarCluster’s source code is stored on github.com. It is preferred that you use github.com to submit patches and enhancements via pull requests. The first step is to sign up for a github account.

Fork the StarCluster project

Once you have a github account the next step is to fork the StarCluster github repository. To do this you must first login to github and then navigate to the StarCluster repository. Once there click on the Fork button towards the top right of the project page:

_images/forkproject.png

This will create your own copy of the StarCluster repository under your github account that you can modify and commit to. Having your own copy allows you to work on bug fixes, docs, new features, etc. without needing special commit access to the main StarCluster repository.

Setup a virtualenv for StarCluster development

When developing a Python project it’s useful to work inside an isolated Python environment that lives inside your $HOME folder. This helps to avoid dependency version mismatches between projects and also removes the need to obtain root privileges to install Python modules/packages for development.

Fortunately there exists a couple of projects that make creating and managing isolated Python environments quick and easy:

To get started you first need to install and configure virtualenv and virtualenvwrapper:

Warning

You need root access to run the sudo commands below.

$ sudo easy_install virtualenv
$ sudo easy_install virtualenvwrapper
$ mkdir $HOME/.virtualenvs
$ echo "source /usr/local/bin/virtualenvwrapper.sh" >> $HOME/.bashrc

If you’re using zsh then the last line should be changed to:

$ echo "source /usr/local/bin/virtualenvwrapper.sh" >> $HOME/.zshrc

Running these commands will install both virtualenv and virtualenvwrapper and configure virtualenvwrapper to use $HOME/.virtualenvs as the top-level virtual environment directory where all virtual environments are installed.

At this point you will either need to close your current shell and launch a new shell or re-source your shell’s rc file:

$ source $HOME/.bashrc

This will reload your shell’s configuration file and configure virtualenvwrapper. The next step is to create a new virtual environment called starcluster and change into that virtual environment:

$ mkvirtualenv --clear --no-site-packages --distribute starcluster
(starcluster)$ echo $PATH
/home/user/.virtualenvs/starcluster/bin:/usr/local/bin:/usr/bin:/bin:/opt/bin

Running this command will create a new folder $HOME/.virtualenvs/starcluster containing your new isolated Python environment for StarCluster. This command will also modify your current shell’s environment to work with the StarCluster virtual environment. As you can see from the echo $PATH command above your PATH environment variable has been modified to include the virtual environment’s bin directory at the front of the path. This means when you type python or other Python-related commands (e.g. easy_install, pip, etc.) you