Submitting a patch to RapidSMS

This example outlines how to use distribute, pip and virtualenv to fix and submit a patch to RapidSMS.

To begin, let’s say we have a RapidSMS project, myproject, that’s running rapidsms==0.9.3a installed using pip. During development, we discover a bug or want to add a feature to RapidSMS core or contrib. How do we submit a patch?

First, fork rapidsms-core-dev and rapidsms-contrib-apps-dev on GitHub. All future changes will be pushed here for RapidSMS core devs to review.

Next, we’ll need to remove rapidsms==0.9.3a from our virtual environment and install our forked version for testing. Uninstalling is easy with pip:

~/myproject$ workon project
(project)~/myproject$ pip uninstall rapidsms

To install a version for testing, clone the forked rapidsms-core-dev repository and update it’s submodules:

(project)~$ git clone [email protected]:copelco/rapidsms-core-dev.git rapidsms-fork
(project)~$ cd rapidsms-fork
(project)~/rapidsms-fork$ git submodule init
(project)~/rapidsms-fork$ git submodule update

Install forked RapidSMS in development mode:

(project)~/rapidsms-fork$ python setup.py develop

Now any changes made to rapidsms-fork will immediately be available in myproject. Further, you can run the RapidSMS test suite from your project:

(project)~/myproject$ ./manage.py test rapidsms

Say we found a bug in rapidsms.contrib.scheduler. We’ll fix and write tests for the bug in rapidsms-fork and push the changes back to the rapidsms-contrib-apps-dev fork on GitHub. Before making any changes to contrib, make sure to create a branch first. As the submodule has a detached head (checked out at a specific revision, but not within a branch), you’ll want to create a branch to work on contrib changes. See Issues with Submodules in ProGit for more information. So, let’s create a scheduler branch and commit our changes:

(project)~/rapidsms-fork/lib/rapidsms/contrib$ git checkout -b scheduler
... make changes ...
(project)~/rapidsms-fork/lib/rapidsms/contrib$ git commit

To push our changes up to GitHub, we’ll need to use git remote first. The rapidsms-contrib-apps-dev submodule still references the official contrib repository. We can’t push our changes there, so we need to add our remote repository. Add the SSH URL to your rapidsms-contrib-apps-dev fork, for example:

(project)~/rapidsms-fork/lib/rapidsms/contrib$ git remote add push [email protected]:copelco/rapidsms-contrib-apps-dev.git

Now you can push the scheduler branch like so:

(project)~/rapidsms-fork/lib/rapidsms/contrib$ git push push scheduler

GitHub allows you to easily compare branches as well, so you can get an itemized list of all changes made. For example:

http://github.com/copelco/rapidsms-contrib-apps-dev/compare/copelco:master...copelco:scheduler-12

Using a non-official package of RapidSMS

Since RapidSMS uses git submodules, it’s a bit of a pain to install a patched version of RapidSMS using pip. Ideally, if submodules weren’t in the picture, we could simply point pip to our GitHub fork:

(project)~/myproject$ pip install -e git+http://github.com/copelco/rapidsms-core-dev.git#egg=rapidsms

This isn’t currently possible with RapidSMS however, due to the fact that contrib is a submodule in core. As a workaround, we can simply tar up our checkout of rapidsms-core-dev and distribute it with our project:

# remove git data for a smaller archive
(project)~$ find rapidsms-fork -name .git | xargs rm -rf
# gzip rapidsms fork
(project)~$ tar -czf rapidsms.tar.gz rapidsms-fork/

Now you can easily install this archive using pip:

(project)~$ pip install rapidsms.tar.gz