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