Submitting Pull Requests

Before submitting a Pull Request, please review each of the following items.

Coding Guidelines and Conventions

We expect submitted code to follow our code conventions and styling. We also have careful guidelines about app structure and inter-app dependencies, including expectations about how commits are structured.

Documentation

For all new features and any major changes (including class or function additions) for bugfixes, we require documentation to be submitted along with code changes.

For comments, we follow Google's Python Style Guide, which contain docstring formatting instructions.

We use docstrings & comments for each of the following

• New modules / apps: docstring in the module's __init__.py, explaining the high-level need, design, and dependencies.
• New files: docstring at the top of the file defining what lives inside, and any overall design.
• New functions/classes: docstring for each
• Inline: as needed

Here's an example of the standard docstring for a public function:

def public_fn_with_googley_docstring(name, state=None):
    """This function does something.

    Args:
       name (str):  The name to use.

    Kwargs:
       state (bool): Current state to be in.

    Returns:
       int.  The return code::

          0 -- Success!
          1 -- No good.
          2 -- Try again.

    Raises:
       AttributeError, KeyError

    A really great idea.  A way you might use me is

    >>> print public_fn_with_googley_docstring(name='foo', state=None)
    0

    BTW, this always returns 0.  **NEVER** use with :class:`MyPublicClass`.

    """
    return 0

Testing

Test Types

We have four types of tests in our repository.

• Unit tests - These tests are direct tests of function inputs and outputs.
• API tests - These tests use a programmable HTTP client to test API inputs and outputs.
• Browser tests - These tests use a browser to click links, submit forms, examine elements, and test end-user experience.
• Ecosystem tests - These tests must be run from our central server repository. These tests install multiple versions of KA Lite (including the central server) to test data sharing across installations.

We use Django's extension of the unittest framework for unit tests, Django's LiveServerTest for any tests requiring KA Lite to be running (API, Browser, and Ecosystem tests), and selenium to launch and run Browser tests.

Test Requirements

All new features must have unit tests, and should use other types of tests as applicable (see below for examples). Regression tests (tests for bugs that have been found) can be in whatever test type is applicable as well.

Test Structure and Tools

Files should be contained within the app in a tests directory.

• If no such directory exists, create one! Copy an __init__.py from an existing test repository--it contains code needed for loading all tests into the `kalite.{app}.

Test Classes and Examples

Unit Tests

API Tests

Browser Tests