# 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](https://cla.developers.google.com/about) (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](https://opensource.google/conduct/).

## Contribution process

### Development setup

1. Install the package with development dependencies:

   ```bash
   uv pip install -e ".[dev]"
   ```

2. Install pre-commit hooks:

   ```bash
   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](https://docs.astral.sh/ruff/) for linting and formatting. Run it with:
  ```bash
  ruff check .
  ```
- **Unit tests:** We use [Pytest](https://docs.pytest.org/) for unit tests. Run them with:

  ```bash
  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:**

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

  **Run a specific test file:**

  ```bash
  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](https://help.github.com/articles/about-pull-requests/) for more
information on using pull requests.

## Documentation Contribution Process

```sh
# 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:
   ```bash
   uv pip install -e ".[release]"
   ```
2. Bump the version in the following files:
   - [pyproject.toml](../pyproject.toml)
   - [version.py](../kinetic/version.py)
3. Build the source distribution and wheel:
   ```bash
   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:
   ```bash
   TWINE_USERNAME=__token__ TWINE_PASSWORD=pypi-... python3 -m twine upload dist/*
   ```
5. Create a new release on GitHub using the `gh` CLI, e.g.:
   ```bash
   gh release create 0.0.2
   ```