Contributing to pdp
¶
Reporting bugs and errors¶
If you find a bug, or an error in the code or documentation, please report this by raising an issue at the GitHub issues page for pdp
:
Contributing code or documentation¶
We gratefully accept code contributions, if you would like to fix a bug, improve documentation, or extend pdp
. To make everyone’s lives easier in this process, we ask that you please follow the guidelines below:
Pre-commit checks and style guide¶
So far as is possible, we aim to follow the coding conventions as described in PEP8 and PEP257, but we have adopted black
code styling, which does vary from the PEPs in places.
We use the flake8 tool for style checks, and this can be installed as follows (with two useful plugins):
pip install flake8 flake8-docstrings flake8-blind-except
flake8 can then be run directly on the codebase with
flake8 bin/
flake8 pyani/
We use the black tool for code style checking, which can be installed with:
pip install black
The flake8` and ``black
styles can be enforced as pre-commit hooks using the pre-commit package (included in requirements.txt
).
The black
and flake8
hooks are defined in .pre-commit-config.yaml
; custom settings for flake8
are held in .flake8
(all files are under version control).
To enable pre-commit checks in the codebase on your local machine (once pre-commit
has been installed), execute the following command in the root directory of this repository:
pre-commit install
Checking changes to the documentation¶
Much of the repository documentation is written in Markdown files, but the main documentation (which you are reading) is prepared for ReadTheDocs, which uses reStructuredText and Sphinx
. The Sphinx
configuration is described in docs/conf.py
(under version control).
So long as Sphinx
is installed on your machine, you can check your documentation changes locally, building inplace by changing to the docs/
directory and issuing:
make html
This will place a compiled version of the documentation under _build/html
, which you can inspect before committing to the repository.
Tip
To build the documentation in ReadTheDocs
style, you will need to install the corresponding theme with pip install sphinx_rtd_theme
or conda install sphinx_rtd_theme
For now, docstrings in the source code are not required to be in any controlled syntax, such as reStructuredText, but this may change.
Making changes and pull requests¶
- Fork the
find_differential_primers
repository under your account at GitHub. - Clone your fork to your development machine.
- Create a new branch in your forked repository with an informative name like
fix_issue_107
, usinggit
(e.g. with the commandgit checkout -b fix_issue_107
). - Make the changes you need and commit them to your local branch.
- Run the repository tests (see the Testing documentation for more details).
- If the tests all pass, push the changes to your fork, and submit a pull request against the original repository.
- Indicate one of the
pdp
developers as an assignee to review your pull request when you submit your pull request.
The assigned developer will then review your pull request, and merge it or continue the conversation, as appropriate.
Suggestions for improvement¶
If you would like to make a suggestion for how we could improve pdp
,
we welcome contributions at the GitHub issues page.