Contributing¶

Clifft is developed at unitaryfoundation/clifft on GitHub.

Reporting Issues¶

Bugs: Use the bug report template with a minimal reproducer.
Feature requests: Use the feature request template.

Development Workflow¶

Fork the repository and create a feature branch
Make your changes with atomic, conventional commits (feat:, fix:, test:, docs:)
Run pre-commit checks before committing
Open a pull request against main

Contributor Agreement¶

By submitting a pull request, you confirm that:

The contribution is your original work (or you have the right to submit it).
You license it under this project's Apache-2.0 license.

The PR template includes a checkbox for this — please check it when opening your PR.

AI-Assisted Contributions¶

We welcome AI-assisted contributions. If you use AI tools (Claude, Copilot, ChatGPT, etc.) to help write code:

Review all generated code before submitting. You are responsible for the correctness, security, and quality of the contribution.

Include an Assisted-by: git trailer in your commit message identifying the tool and model used:

feat: add new optimization pass

Assisted-by: Claude (Sonnet 4.6) <noreply@anthropic.com>

The human author remains the commit author. The AI tool is credited via the trailer, not Co-authored-by.

Users that do not follow these steps, and in particular fail to do a human pre-review of any AI generated content including issues and pull requests, may be subject to a ban from the repo.

Code Quality¶

We use pre-commit hooks to enforce formatting and linting:

# Install pre-commit hooks (runs automatically on git commit)
uv run pre-commit install

# Run all checks manually
uv run pre-commit run --all-files

C++¶

Formatter: clang-format
Standard: C++20
Namespace: All code in namespace clifft { ... }
Comments: Explain why, not what. Omit if the code is self-explanatory.

Python¶

Linter/Formatter: Ruff
Type checker: mypy (strict mode)
Python version: 3.12+

Running Tests¶

PythonC++Both

uv run pytest tests/python/ -v

cmake -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j
ctest --test-dir build -E Bench --output-on-failure

-E Bench skips the [bench] performance cases. Run them explicitly with ctest --test-dir build -R Bench when you want timing data.

just py-test
just test

Code Coverage¶

# Python coverage
just py-cov

# C++ coverage (requires lcov)
just cpp-cov

# Both
just cov

HTML reports are generated at coverage/python/index.html and coverage/cpp/index.html.