Contribution Guidelines
***********************

Please follow the following contribution guidelines when contributing
a pull request.


Code style
==========

We follow the PEP 8 style guide for Python. The test suite includes a
test that enforces the required style, so all you need to do is run
the tests to ensure your code follows the style. If the unit test
passes, you are good to go!


Unit tests
==========

Greenwave uses the Python unittest framework for unit tests.

Patches should be accompanied by one or more tests to demonstrate the
feature or bugfix works. This makes the review process much easier
since it allows the reviewer to run your code with very little effort,
and it lets developers know when they break your code.


Running Tests
-------------

Tests are run with py.test via tox. You can run individual
environments by using the "-e" flag. For example, "tox -e lint" runs
the linter.


Test Organization
-----------------

The test organization is as follows:

1. Each module in the application has a corresponding test module.
   These modules is organized in the test package to mirror the
   package they test. That is, "greenwave/app.py" has a test module in
   located at "greenwave/tests/test_app.py"

2. Within each test module, follow the unittest code organization
   guidelines.

3. Include documentation blocks for each test case that explain the
   goal of the test.


Documentation
=============

Greenwave uses sphinx to create its documentation. New packages,
modules, classes, methods, functions, and attributes all should be
documented using "Google style" docstrings.

Python API documentation is automatically generated from the code
using Sphinx's autodoc extension. HTTP REST API documentation is
automatically generated from the code using the httpdomain extension.


Development Environment
=======================

Set up a Python virtual environment and then install Greenwave:

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