Contributing to `contract-checker`¶

contract-checker is open source software. Whether you are a seasoned open source contributor or a first-time committer, we welcome and encourage you to contribute code, documentation, ideas, or problem statements to this project.

About this document¶

There are many ways to contribute to the ongoing development of contract-checker, such as by participating in discussions and issues.

The rest of this document serves as a more granular guide for contributing code changes to contract-checker (this repository). It is not intended as a guide for using contract-checker, and some pieces assume a level of familiarity with Python development (virtualenvs, uv, etc). Specific code snippets in this guide assume you are using macOS or Linux and are comfortable with the command line.

If you get stuck, we're happy to help! Just open an issue or draft PR and we'll do our best to help out.

Note¶

Branches: All pull requests from community contributors should target the main branch (default).

Getting the code¶

Installing git¶

You will need git in order to download and modify the contract-checker source code. On macOS, the best way to download git is to just install Xcode.

Contributors¶

You can contribute to contract-checker by forking the contract-checker repository. For a detailed overview on forking, check out the GitHub docs on forking. In short, you will need to:

Fork the contract-checker repository.
Clone your fork locally.
Check out a new branch for your proposed changes.
Push changes to your fork.
Open a pull request from your forked repository.

Setting up an environment¶

There are some tools that will be helpful to you in developing locally. While this is the list relevant for contract-checker development, many of these tools are used commonly across open-source python projects.

Tools¶

These are the tools used in contract-checker development and testing:

typer to create our CLI interface.
GitHub Actions for automating tests and checks, once a PR is pushed to the contract-checker repository.
make to run multiple setup or test steps in combination.
mypy for static type checking.
uv to manage our python virtual environment and dependencies.
pre-commit to easily run those checks.
Pydantic for data validation.
pytest to define, discover, and run tests.
Ruff to lint and format python code.

A deep understanding of these tools in not required to effectively contribute to contract-checker, but we recommend checking out the attached documentation if you're interested in learning more about each one.

Virtual environments¶

We strongly recommend using virtual environments when developing code in contract-checker. We recommend creating this virtualenv in the root of the contract-checker repository. To create and activate a new virtualenv, run:

uv venv && source .venv/bin/activate

This creates an empty Python virtual environment in .venv/; the dependencies are installed in the next step.

Running `contract-checker` in development¶

Installation¶

First make sure that you set up your virtualenv as described in Setting up an environment. Next, install contract-checker, its dependencies and pre-commit:

make install
uv run pre-commit install

When installed in this way, any changes you make to your local copy of the source code will be reflected immediately in your next contract-checker run.

Running `contract-checker`¶

With your virtualenv activated, you can run contract-checker using the provided example configuration file (data-contract-checks.example.yml) via:

uv run contract-checker --help
make validate-examples   # runs the example config against tests/fixtures/dcs/
uv run contract-checker --checks-config-path data-contract-checks.example.yml --contract-path tests/fixtures/dcs/1.2.0/
uv run contract-checker --checks-config-path data-contract-checks.example.yml --output-mode full --verbose   # also show passing checks, plus debug logging

Testing¶

Once you're able to manually test that your code change is working as expected, it's important to run existing automated tests, as well as adding some new ones. These tests will ensure that: - Your code changes do not unexpectedly break other established functionality - Your code changes can handle all known edge cases - The functionality you're adding will keep working in the future

Test commands¶

There are a few methods for running tests locally.

`makefile`¶

There are multiple targets in the makefile to run common test suites:

# Runs unit tests
make test-unit

# Runs all tests
make test

`pre-commit`¶

pre-commit takes care of running all code-checks for formatting and linting. Run uv run pre-commit install to install pre-commit in your local environment. Once this is done you can use the git pre-commit hooks to ensure proper formatting and linting.

`pytest`¶

Finally, you can also run a specific test or group of tests using pytest directly. With dev dependencies installed you can do things like:

# run all unit tests
uv run pytest ./tests/unit

# run all unit tests in a file
uv run pytest ./tests/unit/test_cli.py

# run a specific unit test
uv run pytest ./tests/unit/test_cli.py::test_specific_function

See pytest usage docs for an overview of useful command-line options.

Assorted development tips¶

Append # type: ignore to the end of a line if you need to disable mypy on that line, preferably with the specific rule to ignore such as # type: ignore[union-attr].

Adding a new check¶

To add a new check follow the below steps:

In ./src/contract_checker/checks/validators/ create a new file for your check (e.g., my_check.py), or add to an existing file if appropriate.

Create a new class that inherits from Check (from contract_checker.checks.base). Your class must:

Implement the check_type property that returns a unique string identifier (e.g., "my_custom_check").
Implement the execute method that performs the validation and returns a list of ValidationResult objects.
Have a clear message in the event of a failure.
Optionally override validate_config to reject configuration values your execute cannot handle. It is called once per config entry before any contract is read; raise ValueError with a message saying what is wrong. The error is then reported once as a configuration error (naming the entry) instead of failing every contract. Without an override, any value is accepted.

Example:

from typing import Any, List
from contract_checker.checks.base import Check
from contract_checker.checks.models import ValidationResult

class MyCustomCheck(Check):
    @property
    def check_type(self) -> str:
        return "my_custom_check"

    def validate_config(self, check_value: Any) -> None:
        if not isinstance(check_value, bool):
            raise ValueError(f"'my_custom_check' expects true or false, got {check_value!r}")

    def execute(
        self,
        field_path: str,
        values: List[Any],
        check_value: Any,
    ) -> List[ValidationResult]:
        results = []
        for value in values:
            passed = value is not None  # Your validation logic here
            message = "Passed" if passed else f"Field '{field_path}' failed custom check"
            results.append(
                ValidationResult("", field_path, self.check_type, passed, message)
            )
        return results

Export your check from ./src/contract_checker/checks/validators/__init__.py (import it and add it to __all__), and register it in ./src/contract_checker/checks/registry.py (import it and add it to _register_default_checks).
Add the check to data-contract-checks.example.yml and run make validate-examples to ensure the check works as expected.
Add at least one happy path and one unhappy path test to ./tests/unit/test_checks.py.
Document the check in ./docs/checks.md and add it to the checks table in README.md.
Run make test to ensure the tests pass.
Open a PR!

Submitting a Pull Request¶

Code can be merged into the current development branch main by opening a pull request. Give it a Conventional Commits title (feat: …, fix: …, docs: …, ci: …). PRs are squash-merged into main: the whole PR becomes a single commit whose message is the PR title and description, so there's no need to tidy up the individual commits on your branch. If the proposal looks like it's on the right track, then a contract-checker maintainer will review the PR. They may suggest code revision for style or clarity, or request that you add unit or integration test(s). These are good things! We believe that, with a little bit of help, anyone can contribute high-quality code. Once merged, your contribution will be available for the next release of contract-checker.

Automated tests run via GitHub Actions. If you're a first-time contributor, all tests will require a maintainer to approve.

Every PR needs an approval from a code owner (see .github/CODEOWNERS). Once all tests are passing and your PR has been approved, a contract-checker maintainer will merge your changes into the active development branch. And that's it! Happy developing :tada:

Contributing to contract-checker¶