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
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¶
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
We use the
black tool for code style checking, which can be installed with:
pip install black
flake8` and ``black styles can be enforced as pre-commit hooks using the pre-commit package (included in
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:
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 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:
This will place a compiled version of the documentation under
_build/html, which you can inspect before committing to the repository.
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
pyanirepository 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
git(e.g. with the command
git 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
pyanidevelopers 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.