Contributing

We welcome contributions! But we are new at this, so please be patient. Right now, we (try to) follow these conventions:

Workflow

Download the test dataset

Get the test dataset and unpack it into plastid/test/. The archive will create a folder called data and you’ll be good to go.

Start with a ticket

Before submitting a patch, please open a ticket. This will allow public discussion of the best way to solve an issue or design a feature, and allows us to keep logical records of everything.

Create a fork

Rather than push changes to our main repository, create a fork, and, if appropriate, a topic branch. Build & test your changes there, merge into the develop branch of your fork, then submit a pull request.

Test

We advocate test-driven development. Feature additions will not be accepted without companion tests, and, where appropriate, test datasets. Before submitting a change, please:

  1. Write new tests. Consider using the existing test dataset.

  2. Run your new tests, make sure they pass

  3. Run the existing tests.

    • If they pass, great!
    • If they fail because of an intentional design change in an object’s behavior, make corresponding changes to the test dataset and discuss this heavily in the update- this will probably require a version bump.
    • If they fail otherwise, fix your submission so the old tests pass.

Document

  1. Document everything heavily, updating module & object docstrings where appropriate, as well as any Tutorials that might be affected by the change or addition.
  2. If you use technical terms, please check if a synonym of your term is already defined in the glossary, and then use that. If no synonym is present, please add the glossary, and refer to it using the :term: directive.

Submit

Send a pull request referring to the ticket above, along with a description of your patch. We’ll merge it into develop, and add you to the list of contributors.

Document formatting

Code should be formatted as described in PEP 8, noting especially to use four spaces for indentation.

Docstring & module documenation

Docstrings & documentation should be formatted in reStructuredText using the most human-readable raw form possible. This means:

  • Format docstrings for numpydoc, as described in the numpy documentation guide
  • Follow PEP 257 for docstring style
  • Refer to classes defined in plastid in docstrings using the shortcut |ClassName| rather than as :py:class:`package.module.ClassName`, because the shortcuts are easier to read.
  • Similarly, refer to command-line scripts as |modname|, where modname is the name of the module, excluding the extension. e.g. |metagene| for :mod:`plastid.bin.metagene`.
  • Decorate any function that you don’t want to be put in the online documentation with the skipdoc() decorator
  • Module docstrings for command-line scripts should have a section called Output files, and, where appropriate, examples of how to call the script.