Contributing

Everyone can contribute to Model Validation Toolkit, and we value everyone’s contributions. There are several ways to contribute, including:

Answering questions on Model Validation Toolkit’s Gitter channel
Improving or expanding Model Validation Toolkit’s documentation
Contributing to Model Validation Toolkit’s code-base

Ways to contribute

We welcome pull requests, in particular for those issues marked with contributions welcome or good first issue.

For other proposals, we ask that you first open a GitHub Issue or Gitter channel

to seek feedback on your planned contribution.

Contributing code using pull requests

We do all of our development using git, so basic knowledge is assumed.

Follow these steps to contribute code:

Fork the Model Validation Toolkit repository by clicking the Fork button on the repository page. This creates a copy of the Model Validation Toolkit repository in your own account.
Install Python >=3.6 locally in order to run tests.

pip installing your fork from source. This allows you to modify the code and immediately test it out:

git clone https://github.com/YOUR_USERNAME/model-validation-toolkit
cd model-validation-toolkit
pip install -e .  # Installs Model Validation Toolkit from the current directory in editable mode.

Add the Model Validation Toolkit repo as an upstream remote, so you can use it to sync your changes.
```
git remote add upstream http://www.github.com/FINRAOS/model-validation-toolkit
```
Create a branch where you will develop from:
```
git checkout -b name-of-change
```
And implement your changes using your favorite editor.
Make sure the tests pass by running the following command from the top of the repository:
```
pytest tests/
```
If you know the specific test file that covers your changes, you can limit the tests to that; for example:
```
pytest tests/supervisor
```
Model Validation Toolkit also offers more fine-grained control over which particular tests are run; see running-tests for more information.
Once you are satisfied with your change, create a commit as follows (how to write a commit message):
```
git add file1.py file2.py ...
git commit -s -m "Your commit message"
```
Please be sure to sign off your work when you commit it with the -s or, equivalently --sign-off flag to agree to our DCO.

Then sync your code with the main repo:
```
git fetch upstream
git rebase upstream/main
```
Finally, push your commit on your development branch and create a remote branch in your fork that you can use to create a pull request from:
```
git push --set-upstream origin name-of-change
```
Create a pull request from the Model Validation Toolkit repository and send it for review. Check the pr-checklist for considerations when preparing your PR, and consult GitHub Help if you need more information on using pull requests.

Model Validation Toolkit pull request checklist

As you prepare a Model Validation Toolkit pull request, here are a few things to keep in mind:

DCO

By contributing to this project, you agree to our DCO.

Single-change commits and pull requests

A git commit ought to be a self-contained, single change with a descriptive message. This helps with review and with identifying or reverting changes if issues are uncovered later on.

Pull requests typically comprise a single git commit. In preparing a pull request for review, you may need to squash together multiple commits. We ask that you do this prior to sending the PR for review if possible. The git rebase -i command might be useful to this end.

Linting and Type-checking

Model Validation Toolkit uses mypy and flake8 to statically test code quality; the easiest way to run these checks locally is via the pre-commit framework:

pip install pre-commit
pre-commit run --all

Full GitHub test suite

Your PR will automatically be run through a full test suite on GitHub CI, which covers a range of Python versions, dependency versions, and configuration options. It’s normal for these tests to turn up failures that you didn’t catch locally; to fix the issues you can push new commits to your branch.