Contributing to FairLens¶
fairlens is an open source project currently under active development. As such, we appreciate any contributions from
the community. There are many ways you can get involved: filing feature requests or bug reports on our
issue tracker, updating the documentation, or making pull requests
for new features you have developed or bugs you have fixed.
fairlensrepo on GitHub.
Clone your fork locally:
$ git clone firstname.lastname@example.org:your_username/fairlens.git
Set up the development environment. We highly recommend using a virtual environment when developing
fairlens. The most basic approach is to use
venv, which comes by default in Python 3. You can create and activate an environment named
python3 -m venv .env # activate environment source .env/bin/activate
Other tools such as
conda are also suitable. Pick your favourite!
Once your environment is active, you can install
fairlens and all dependencies by running:
pip install -e .[dev,doc,test]
Additionally, we use the pre-commit tool for linting and style checks. This will run
mypy for linting and static type checking, as well as
black for style formatting
on every commit. An up to date list of pre-commit checks can be found in the
To install the
pre-commit hooks in your development environment, run
pip install pre-commit pre-commit install
Create a development branch
git checkout -b name-of-your-bugfix-or-feature-branch Now you can start making changes in your local version of ``fairlens``.
Run tests, and make sure they pass. We use the
pytesttool to create and run unit tests.
All tests should go in the
tests subdirectory of the
Commit and push your changes to GitHub
git push origin name-of-your-bugfix-or-feature
Create a pull request (PR) through GitHub.
To build the documentation run
cd docs make html
This will create static
html files in the
_build folder that can be viewed in your web browser.
Pull Request Guidelines¶
Before you submit a pull request, check that it meets the following guidelines:
The pull request must include tests that cover the functionality you have added. If fixing a bug, include a test that passes with the bug fix.
If adding new functionality the documentation must be updated. All documentation must be included in the
docssubdirectory and be built using
fairlens will use GitHub Actions to run CI workflows on your PR. All workflows must pass before your PR will be reviewed and accepted.