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 (Recommended for dependency management)
Installation
Clone the repository
git clone https://github.com/TracingInsights/tif1.git
cd tif1
Install dependencies
Use uv to create a virtual environment and install all development extras: Install git hooks with prek
Enable automated linting and formatting before every commit:
Testing Workflow
We use pytest for our test suite, with xdist for parallel execution.
Running Tests
Code Coverage
To run tests with coverage reporting:
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.
uv run ruff check src/ tests/
uv run ruff format src/ tests/
- Type Checking: We use
pyright (via ty).
- prek: Run all checks at once.
uv run prek run --all-files
Documentation
Our documentation is built with Mintlify.
Local Development
To preview the documentation locally:
- Install the Mintlify CLI:
npm i -g mintlify
- 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
- Create a branch:
git checkout -b feat/your-awesome-feature
- Implement & Test: Ensure coverage doesn’t drop.
- Commit: Use Conventional Commits (e.g.,
feat:, fix:, docs:, perf:).
- Push & Open PR: Provide a clear description of what changed and why.
Check the CHANGELOG.md and add a summary of your changes there as well.
