Getting the code for development

Here’s how you can get the RapidSMS source code and make changes to it.

Git

The RapidSMS project uses Git to manage its source code. If you’re not familiar with Git already, you’ll find it useful knowledge for more than working on RapidSMS. Git is an incredibly popular source control tool, and there is a huge amount of documentation on the net ranging from introductory tutorials to in-depth reference material.

Clone the repository

Clone the RapidSMS source repository from Github:

$ git clone git://github.com/rapidsms/rapidsms.git
Cloning into 'rapidsms'...
remote: Counting objects: 25262, done.
remote: Compressing objects: 100% (8696/8696), done.
remote: Total 25262 (delta 15920), reused 24482 (delta 15498)
Receiving objects: 100% (25262/25262), 5.20 MiB | 1.09 MiB/s, done.
Resolving deltas: 100% (15920/15920), done.

You’ll now have a new rapidsms subdirectory containing the code.

Environment

Install virtualenv and virtualenvwrapper (see Using virtualenv).

Change into the rapidsms directory:

$ cd rapidsms
$

Create a virtual environment to work in and activate it:

$ mkvirtualenv --no-site-packages rapidsms
...
$

Master branch

The default branch in the RapidSMS repository is develop, because that’s the branch used when working on new features for an upcoming release, and so most developers use it a lot.

But let’s switch to the stable branch, master, for now, so we can run the tests and verify that we have things set up right.

$ git checkout master
Branch master set up to track remote branch master from origin.
Switched to a new branch 'master'
$

Requirements

Install RapidSMS’s requirements using distribute’s develop command:

$ python setup.py develop
[lots of output omitted]
$

Tests

Verify that everything is okay by running RapidSMS’s tests.

$ tox
[lots of output omitted]
____________________________________________ summary _____________________________________________
  py26-1.4.X: commands succeeded
  py26-1.5.X: commands succeeded
  py26-trunk: commands succeeded
  py27-1.4.X: commands succeeded
  py27-1.5.X: commands succeeded
  py27-trunk: commands succeeded
  congratulations :)
$

This takes a while the first time – over 8 minutes on my computer. But after that, the environments are already set up and it’ll run much faster. On my computer, subsequent tests take less than 30 seconds.

The code on the RapidSMS master branch should always pass the tests. If anything fails, review these instructions, and if they still fail, ask on IRC or the rapidsms-dev mailing list.

Work on a branch

When you’re ready to start making changes, you’ll want to create a new branch. You have a choice to base your branch on the master or develop branch. The tip of the master branch is always the latest released code. It’s stable, but does not include any changes currently under development for the next release.

The develop branch contains changes that are ready for the next release. It should also be pretty stable, because all changes are developed on other branches and not merged into develop until they appear to be ready, but there’s a bit more chance of there being something broken in develop.

It’s probably a good idea to base your branch on develop if possible, because if you work from master, there might be changes already in develop that your work won’t take into account.