> ## Documentation Index
> Fetch the complete documentation index at: https://tif1.tracinginsights.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

> Guidelines for developing and contributing to tif1

Thank you for your interest in contributing to `tif1`! This guide will help you set up your environment and understand our development workflow.

## Development Setup

### Prerequisites

* **Python 3.10+**
* **[uv](https://github.com/astral-sh/uv)** (Recommended for dependency management)

### Installation

<Steps>
  <Step title="Clone the repository">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    git clone https://github.com/TracingInsights/tif1.git
    cd tif1
    ```
  </Step>

  <Step title="Install dependencies">
    Use `uv` to create a virtual environment and install all development extras:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    uv sync --all-extras
    ```
  </Step>

  <Step title="Install git hooks with prek">
    Enable automated linting and formatting before every commit:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    uv run prek install
    ```
  </Step>
</Steps>

***

## Testing Workflow

We use `pytest` for our test suite, with `xdist` for parallel execution.

### Running Tests

<CodeGroup>
  ```bash All Tests theme={"theme":{"light":"github-light","dark":"github-dark"}}
  uv run pytest tests/ -v
  ```

  ```bash Unit Only theme={"theme":{"light":"github-light","dark":"github-dark"}}
  uv run pytest tests/ -v -m "not integration"
  ```

  ```bash Integration theme={"theme":{"light":"github-light","dark":"github-dark"}}
  uv run pytest -o addopts='' tests/ -v -n 0 -m integration
  ```

  ```bash Benchmarks theme={"theme":{"light":"github-light","dark":"github-dark"}}
  uv run pytest -o addopts='' tests/test_benchmarks.py -v -m benchmark --benchmark-only --no-cov -n 0
  ```
</CodeGroup>

### Code Coverage

To run tests with coverage reporting:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
uv run pytest -o addopts='' tests/ -v -n auto --dist=loadfile --cov=src/tif1 --cov-report=html
```

***

## Code Quality

Before submitting a PR, ensure your code passes all quality checks.

* **Linting & Formatting:** We use `ruff`.
  ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
  uv run ruff check src/ tests/
  uv run ruff format src/ tests/
  ```
* **Type Checking:** We use `pyright` (via `ty`).
  ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
  uv run ty check src/tif1
  ```
* **prek:** Run all checks at once.
  ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
  uv run prek run --all-files
  ```

***

## Documentation

Our documentation is built with **Mintlify**.

### Local Development

To preview the documentation locally:

1. Install the Mintlify CLI: `npm i -g mintlify`
2. Run the dev server in the `docs` directory: `mintlify dev`

### Guidelines

* Use **Google-style** docstrings for all public functions.
* Update `mint.json` if you add new pages.
* Use Mintlify components (`<Steps>`, `<Card>`, `<CodeGroup>`) to keep pages engaging.

***

## Pull request process

1. **Create a branch:** `git checkout -b feat/your-awesome-feature`
2. **Implement & Test:** Ensure coverage doesn't drop.
3. **Commit:** Use [Conventional Commits](https://www.conventionalcommits.org/) (e.g., `feat:`, `fix:`, `docs:`, `perf:`).
4. **Push & Open PR:** Provide a clear description of what changed and why.

<Tip>
  Check the **CHANGELOG.md** and add a summary of your changes there as well.
</Tip>