Contributing to RapidSMS¶

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.

2. Create a new virtual environment for RapidSMS. Now we’ll create a new virtual environment to isolate our development:

mkvirtualenv --distribute rapidsms

3. 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

4. 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).
5. 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.

Logging¶

If you want to log in your app, just:

import logging
logger = logging.getLogger(__name__)

and use:

logger.debug("msg")
logger.critical("msg")
logger.exception("msg")
# 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:

LOGGING = {
    ...
    '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:

LOGGING = {
    ...
    '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.

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.