Contributing

Contributing#

We’d love to accept your patches and contributions to this project.

Before you begin#

Sign our Contributor License Agreement#

Contributions to this project must be accompanied by a Contributor License Agreement (CLA). You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project.

If you or your current employer have already signed the Google CLA (even if it was for a different project), you probably don’t need to do it again.

Visit https://cla.developers.google.com/ to see your current agreements or to sign a new one.

Review our community guidelines#

This project follows Google’s Open Source Community Guidelines.

Contribution process#

Development setup#

  1. Install the package with development dependencies:

    uv pip install -e ".[dev]"

  2. Install pre-commit hooks:

    pre-commit install

Code quality and testing#

Before submitting a pull request, please ensure your changes pass linting and unit tests.

  • Linting: We use Ruff for linting and formatting. Run it with:

    ruff check .

  • Unit tests: We use Pytest for unit tests. Run them with:

    pytest

  • E2E tests: End-to-end tests run real workloads against a GKE cluster. They live in tests/e2e/ and are skipped by default unless explicitly enabled.

    Prerequisites:

    • A GCP project with a provisioned GKE cluster.

    • Google Cloud SDK authenticated (gcloud auth login and gcloud auth application-default login)

    • GKE credentials configured: gcloud container clusters get-credentials <KINETIC_CLUSTER> --zone <KINETIC_ZONE> --project <KINETIC_PROJECT>

    • Test dependencies installed: uv pip install -e ".[test,cli]"

    Required environment variables:

    Variable

    Required

    Default

    Description

    E2E_TESTS

    Yes

    —

    Set to 1 to enable e2e tests

    KINETIC_PROJECT

    Yes

    —

    Google Cloud project ID

    KINETIC_ZONE

    No

    us-central1-a

    GKE cluster zone

| KINETIC_CLUSTER | No | kinetic-cluster | GKE cluster name |

Run all e2e tests:

E2E_TESTS=1 KINETIC_PROJECT=my-project python -m pytest tests/e2e/ -v -n auto

Run a specific test file:

E2E_TESTS=1 KINETIC_PROJECT=my-project python -m pytest tests/e2e/cpu_execution_test.py -v

Drop -n auto to run tests serially to make it easier to debug.

Submitting changes#

  1. Fork the repository

  2. Create a feature branch: git checkout -b feature/amazing-feature

  3. Commit your changes: git commit -m 'Add amazing feature'

  4. Push to the branch: git push origin feature/amazing-feature

  5. Open a Pull Request

Code reviews#

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

Documentation Contribution Process#

# Install docs libraries:
pip install .[docs]

# Build and serve docs locally:
sphinx-autobuild docs /tmp/docs

Releases#

To release a new version of the package to PyPI, follow these steps:

  1. Install the release dependencies:

    uv pip install -e ".[release]"

  2. Bump the version in the following files:

  3. Build the source distribution and wheel:

    python3 -m build

  4. Upload the packages to PyPI using twine. To avoid twine hanging while waiting for interactive input, provide your credentials via environment variables (e.g. using an API token) or a ~/.pypirc file:

    TWINE_USERNAME=__token__ TWINE_PASSWORD=pypi-... python3 -m twine upload dist/*

  5. Create a new release on GitHub using the gh CLI, e.g.:

    gh release create 0.0.2