Development Guide

If you would like to write a patch for Greenwave, this document will help you get started.

Quick development setup

As an alternative to using virtualenv, described below, you can install system packages listed in Dockerfile.

Set up Python 3 vitualenv:

$ python3 -m venv --system-site-packages .venv
$ source .venv/bin/activate

Install development dependencies:

$ pip install -r dev-requirements.txt -r requirements.txt

Create a local configuration file:

$ cp conf/ conf/

Run the server:

$ DEV=true python3

The server is now running at <http://localhost:5005> and API calls can be sent to <http://localhost:5005/api/v1.0>.

Running the tests

You can run the unit tests, which live in the greenwave.tests package, with the following command:

$ python3 -m pytest greenwave

There are also functional tests in the functional-tests directory. The functional tests will start their own copy of the ResultsDB, WaiverDB, and Greenwave servers and then send HTTP requests to them.

You can run the functional tests like this:

$ python3 -m pytest functional-tests

The functional tests assume you have ResultsDB and WaiverDB git checkouts in ../resultsdb and ../waiverdb respectively. You can tell it to find them in a different location by passing RESULTSDB or WAIVERDB environment variables.

You can quickly clone the repositories (to parent directory) and update development virtualenv with:

$ git clone ../waiverdb/
$ git clone ../resultsdb/
$ pip install -r ../waiverdb/requirements.txt
$ pip install -r ../resultsdb/requirements.txt

If you’d rather not install all the dependencies necessary to run the functional tests, you may use Vagrant to provision a throw-away virtual machine to run the tests:

You should run smoke test after deploying on stage:

$ py.test-3 functional-tests -m smoke

Docker Compose

For local development, you may want to easily bring up containers of WaiverDB, ResultsDB, and/or Greenwave. For more information on that, see:

Building the documentation

The documentation is built using Sphinx. If you’ve made changes to the documentation, you can build it locally and view it in your browser:

$ cd docs
$ make html
$ firefox _build/html/index.html

Code style

We follow the PEP 8 style guide for Python. You can check your code’s style using flake8:

$ flake8

Additionally, we follow the “Google style” for docstrings.