Contributing to pyClarity¶
We welcome and encourage you to contribute to the development of the pyClarity code base. These guidelines outline how you can do so.
Using pyClarity¶
You can contribute to the development of pyClarity simply by using it. If something isn’t clear then please do ask questions in the Discussion. If you find errors when running the code then please report them using the Issues Bug Template, or if there is a feature or improvement you think pyClarity would benefit from then suggest it using the Issues Feature Template.
If you are new to GitHub and working collaboratively you may find the GitHub Issues documentation useful.
Contributing Code¶
If you have algorithms or code that you would like to contribute then please get in touch by emailing us at claritychallengecontact@gmail.com. We will be happy to help you integrate your contribution into the pyClarity framework; we can even help translate contributions from other languages, e.g. MATLAB.
You are also very welcome to fork the repository and address bugs and features yourself and then create a pull request from the fork. However, there are a number of practices and standards we ask that you adhere to in order to maintain the quality and maintainability of the code base.
Use a Virtual Environment¶
It is recommended that you use a Virtual Environment to undertake development.
Install Development Dependencies¶
Before undertaking development you should install the development requirements defined by pyClarity. To do so you can do one of the following
# Install from Pip
pip install pyclarity.[dev]
# Install from GitHub using Pip
pip install git+ssh://github.com:claritychallenge/clarity.[dev]
# Install from local cloned Git repository
pip install '.[dev]'
Create an issue¶
Before undertaking any development please create an Issue for it here on the pyClarity repository. There are templates for Bug Reports and Feature Requests. This allows maintainers to keep an overview of what work is being undertaken and gives you the opportunity to discuss with them your intended solutions.
Create a Fork¶
Once you have created an issue you can fork the pyClarity repository to your own account and create a branch on which to undertake development.
Coding Style¶
We ask that you adhere to the PEP8 coding style when writing your code. To facilitate this we use a number of linting tools.
pre-commit¶
To ensure these coding conventions are applied to code that is submitted to the main
branch PyClarity uses
pre-commit
and pre-commit.ci
which run Git Hooks before each
commit is made (the former locally, the latter on pull requests) for the above linting (and more e.g. Markdown style is
also checked).
Whilst the pre-commit
Python package will have been installed in your environment when you pip install .[dev]
you
need to install the configured hooks (which are defined in
.precommit-config.yaml
) in your local
copy of the PyClarity repository. To do so run the following from the clarity
directory…
pre-commit install
This installs .git/hooks/pre-commit
commit hook which is triggered each time you make a new commit.
If your commit fails to pass the checks please read the error messages carefully. Some changes are fixed automatically
(e.g. black
will format files in place where it can), but not all changes can be fixed and you should read the output
carefully to find out what you need to manually fix.
pathlib
over os
¶
PyClarity uses the object-orientated package pathlib
throughout the code base for any operations involving the file system and path components as it makes code easier to
read. We ask that any contributions follow this convention and use pathlib
rather than os
. For more on pathlib
see
1 and 2.
IDEs¶
Most popular Integrated Development Environments (IDEs) include plugins that will apply flake8
/ black
to your code
on saving a file.
For information on how to configure some popular IDEs see the following links.
Testing¶
All new code should be covered by unit tests with at least 70% coverage and where appropriate regression tests. This includes bug fixes, when a test should be added that captures the bug.
The pytest framework is used and the conventions are followed under
pyClarity. Tests reside under the tests
directory (and optionally within a module directory), fixtures should be defined
in conftest.py
files whilst resources used should be placed under tests/resources
.
The Continuous Integration in place on GitHub Actions runs pytest
on newly created pull-requests and these have to
pass successfully before merging so it is useful to ensure they pass before you create pull requests at the very
least. Sometimes it may be sensible to run them against commits too.
To run the tests you should install the additional dependencies and then call pytest
from the root of the project
folder.
pip install .[tests]
pytest