Development happens against the
main branch following the
GitHub flow model.
Contributors should use their own forks of the repository. In their fork, they
create feature branches off of
main, and their pull requests should
main branch. Maintainers are responsible for prompt
review of pull requests.
Pull requests against
main trigger automated tests that are run
through Azure DevOps, GitHub Actions, and CircleCI. Additional test suites are
run periodically. When adding new code paths or features, tests are a
requirement to complete a pull request. They should be added in the
Documentation should be provided with pull requests that add or change functionality. This includes comments in the code itself, docstrings, and user guides. For exceptions to this rule the pull request author should coordinate with a maintainer. For changes that fix bugs, add new features, change APIs, etc., i.e., for changes that are relevant to developers and/or users please also add an entry in CHANGES.md in the section corresponding to the next release, since that’s where your change will be included. If you’re a new contributor please also add yourself to AUTHORS.md.
Docstrings should follow numpydoc format. This is a recent decision by the community. The new policy is to update docstrings that a PR touches, as opposed to changing all the docstrings in one PR.
Advanced installation instructions¶
While working on Fairlearn itself you may want to install it in editable mode. This allows you to test the changed functionality. First, clone the repository locally via
git clone email@example.com:fairlearn/fairlearn.git
To install in editable mode using
pip install -e .
from the repository root path.
To verify that the code works as expected run
python ./scripts/install_requirements.py --pinned False python -m pytest -s ./test/unit
Fairlearn currently includes plotting functionality that requires the
matplotlib package to be installed. Since this is for a niche use case
Fairlearn comes without
matplotlib by default. To install Fairlearn
with its full feature set simply append
customplots to the install
pip install -e .[customplots]
The Requirements Files¶
The prerequisites for Fairlearn are split between three separate files:
requirements.txt contains the prerequisites for the core Fairlearn package
requirements-customplots.txt contains additional prerequisites for the
[customplots]extension for Fairlearn
requirements-dev.txt contains the prerequisites for Fairlearn development (such as flake8 and pytest)
files are consumed
by setup.py to specify the dependencies to be
documented in the wheel files.
To help simplify installation of the prerequisites, we have the
script which runs
pip install on all three of the above files.
This script will also optionally pin the requirements to any lower bound specified (by changing any
== in each file).
Investigating automated test failures¶
For every pull request to
main with automated tests, you can check
the logs of the tests to find the root cause of failures. Our tests currently
run through Azure Pipelines with steps for setup, testing, and teardown. The
Checks tab of a pull request contains a link to the
Azure Pipelines page),
where you can review the logs by clicking on a specific step in the automated
test sequence. If you encounter problems with this workflow, please reach out
through GitHub issues.
To run the same tests locally, find the corresponding pipeline definition (a
yml file) in the
devops directory. It either directly contains
the command to execute the tests (usually starting with
python -m pytest) or it refers to a template file with the command.