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.

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 master 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. Make sure to add yourself to AUTHORS.
  9. Send a pull request and request feedback on rapidsms-dev.
  10. 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 setup.py 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.

 

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 actually build the documentation locally, you’ll currently 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.