We welcome contributions! But we are new at this, so please be patient. Right now, we (try to) follow these conventions:
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.
We advocate test-driven development. Feature additions will not be accepted without companion tests, and, where appropriate, test datasets. Before submitting a change, please:
Write new tests. Consider using the existing test dataset.
Run your new tests, make sure they pass
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 everything heavily, updating module & object docstrings where appropriate, as well as any Tutorials that might be affected by the change or addition.
- 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
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
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
plastidin 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
- Module docstrings for command-line scripts should have a section called Output files, and, where appropriate, examples of how to call the script.