Contributing to pyani
¶
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 pyani
:
Contributing code or documentation¶
We gratefully accept code and other contributions. A list of contributors can be found via the Github contributors link.
You are welcome to help develop pyani
, fix a bug, improve documentation, or contribute in any other way. To make everyone’s lives easier in this process, we ask that you please follow the guidelines for developers 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
pyani
repository under your account at GitHub. - Clone your fork to your development machine.
- To be able to edit pyani and have changes you make take effect immediately without a reinstall (useful for testing), you can run pip install -e . inside the local cloned repository.
- 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
pyani
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 pyani
, we welcome contributions. If you have a specific problem, or a concrete suggestion, you can submit these at the GitHub issues page. If you would like to discuss an idea with the maintainers and the pyani
community, this can be done at the Github discussions page.