Submitting Pull Requests

Documentation and Testing

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

We require unit tests for all new features, selenium-based in-browser tests for front-end testing, and ecosystem tests to tests changes to KA Lite's interaction with our central data repository.