Contributing to RapidSMS

We’re always excited to welcome new volunteers to the RapidSMS project. As it keeps growing, we need more people to help others and contribute back to the community. As soon as you learn RapidSMS, you can contribute in many ways:

  • Join the rapidsms mailing list and answer questions. This users list, the primary RapidSMS mailing list, is used to ask and answer questions, help work through bugs, and discuss general RapidSMS topics.
  • Join the rapidsms-dev mailing list. This list is used to discuss RapidSMS core and active country projects. This ranges from new RapidSMS features to large scale RapidSMS deployments in Zambia. If you’re interested in any of this, please join the conversation!
  • Join the #rapidsms IRC channel on Freenode and answer questions. By explaining RapidSMS to other users, you’re going to learn a lot about the framework yourself. You can use the webchat client for this too.

And, of course, you can help out by working on RapidSMS.

  • Report bugs in our ticket tracker.
  • Open pull requests for features and bug fixes against the develop branch. We use the Gitflow model for our development.
  • Comment on open issues and pull requests. Try the changes yourself and report on how well they work in the issue or pull request.
  • Improve the RapidSMS documentation (what you’re reading now!).
  • Participate on the rapidsms-dev mailing list.

Submitting code

  1. Check for open issues or open a fresh issue in the ticket tracker to start a discussion around a feature idea or a bug. Send a message to the rapidsms-dev mailing list to request feedback.
  2. If you’re working on a large patch, we highly recommend creating a wiki page under the RapidSMS GitHub account. Use the wiki page to outline the motivation behind the patch and to document decisions made on the rapidsms-dev mailing list. Router decoupling and HTTP message processing, Bulk Messaging API, and Scheduling are good examples.
  3. Fork the repository on GitHub to start making your changes (relative to the develop branch).
  4. Follow the RapidSMS coding standards and run the PEP 8 adherence tool.
  5. Write a test which shows that the bug was fixed or that the feature works as expected.
  6. Run the RapidSMS test suite to make sure nothing unexpected broke. We only accept pull requests with passing tests.
  7. Write new or update old documentation to describe the changes you made.
  8. Add the change to the release notes document for the next release. The release notes should focus on the effects on existing users, particularly if it will require them to make changes.
  9. Make sure to add yourself to AUTHORS.
  10. Open a pull request against the develop branch (see Gitflow), and request feedback on rapidsms-dev.
  11. Sign the Contributor License Agreement.

Coding standards and best practices

  1. Follow PEP8 style conventions. Use 4 spaces instead of tabs.

  2. Use CapitalizedCase for class names, underscored_words for method names.

  3. Code using os.path must be Windows and ‘NIX friendly. For example, check for a file using os.path.join(‘foo’,’bar’) instead of ‘foo/bar’

  4. Be sure every class and method has docstrings.

  5. Add the following two lines to the beginning of your files to automatically configure many text editors (VI, Emacs) to do this automatically:

    #!/usr/bin/env python
    # vim: ai ts=4 sts=4 et sw=4 encoding=utf-8

Using virtualenv

We highly recommend using virtualenv and virtualenvwrapper to work on RapidSMS core. These tools provide isolated Python environments, which are more practical than installing packages system wide. They also allow installing packages without administrator privileges. This section will outline the steps to setup RapidSMS core so that you can edit it while working on a RapidSMS project.

  1. Install virtualenv and virtualenvwrapper. Use pip to install the latest version (and upgrade if you have an older copy):
sudo pip install --upgrade virtualenv
sudo pip install --upgrade virtualenvwrapper

Then follow the virtualenvwrapper install docs to setup your shell properly.

  1. Create a new virtual environment for RapidSMS. Now we’ll create a new virtual environment to isolate our development:
mkvirtualenv --distribute rapidsms
  1. Install RapidSMS in development mode. This install is done in such a way that changes to the RapidSMS source are immediately available in your project, without needing to run a build or install step after each change. To do this, navigate to the RapidSMS clone on your file system and use distribute’s develop command:
cd <your-rapidsms-clone>
python develop
  1. Setup your project. Now we can use our new virtual environment with a RapidSMS project to test changes and modifications. You can create a new project (e.g. by Installing the RapidSMS project template).
  2. Remember to activate your virtualenv. If you restart or need to return to your virtualenv at any point, you can easily reactivate it:
workon rapidsms

Now any changes made to your local RapidSMS clone will be reflected immediately while editing your project.


If you want to log in your app, just:

import logging
logger = logging.getLogger(__name__)

and use:

# etc.

All RapidSMS core logging can now be captured using the 'rapidsms' root logger. (There’s not a lot of logging from the core yet, but pull requests are welcome.)

For example, if you wanted messages from the RapidSMS core to be written to a file “/path/rapidsms.log”, you could define a new handler in the LOGGING setting in Django:

    'handlers': {
        'rapidsms_file': {
            'level': 'DEBUG',
            'class': 'logging.FileHandler',
            'filename': '/path/rapidsms.log',

Setting level to DEBUG means all messages of level DEBUG and lower will be passed through (that’s all of them). Then this handler will write those messages to the file /path/rapidsms.log. They’ll be formatted by the default formatter.

Then configure the rapidsms logger to send messages to that handler:

    'loggers': {
        'rapidsms': {
            'handlers': ['rapidsms_file'],
            'propagate': True,
            'level': 'DEBUG',

Setting level to DEBUG means all messages of level DEBUG and lower will be passed through (that’s all of them).

The logger name rapidsms means any logger to a name that matches that (rapidsms, rapidsms.models, etc) will be passed to this handler to handle.

Setting propagate to True means the same messages will be passed to other handlers if they also match. (This handler does not consume the messages.)

If you created your project with the latest rapidsms-project-template and haven’t changed the settings, all rapidsms logging will be written to rapidsms.log in your project directory.


Writing documentation

We believe RapidSMS needs to treat our documentation like we treat our code. It’s what you’re reading now and is generally the first point of contact for new developers. We value great, well-written documentation and aim to improve it as often as possible. And we’re always looking for help with documentation!

Getting the raw documentation

The official documentation is available on Read the Docs. This is the compiled HTML version. However, we edit it as a collection of text files for maximum flexibility. These files live in the top-level docs/ directory of a RapidSMS release. If you’d like to start contributing to our docs, get the development version of RapidSMS from the source code repository (see Installing the latest development version).

Using Sphinx

Before building the documentation, you must have a version of RapidSMS installed. See the Installing the latest development version guide for instructions on installing RapidSMS.

We use the Sphinx documentation system (based on docutils). To build the documentation locally, you’ll need to install Sphinx:

pip install Sphinx

Then, building the HTML is easy. Just run make from the docs directory:

make html

(or make.bat html on Windows)

To get started contributing, you’ll want to read the reStructuredText Primer. After that, you’ll want to read about the Sphinx-specific markup that’s used to manage metadata, indexing, and cross-references.

Documentation starting points

Typically, documentation changes come in two forms:

  • General improvements: typo corrections, error fixes and better explanations through clearer writing and more examples.
  • New features: documentation of features that have been added to the framework since the last release.

If you’re interested in helping out, a good starting point is with the documentation label on the GitHub issue tracker.

Previous topic

Frequently Asked Questions

This Page