Contributing

Thanks for your interest in contributing. PTWM is a Python + Rust (PyO3) lossless compression library; this guide covers the development setup, the local checks to run before pushing, and the conventions for pull requests.

Reporting issues

• Bugs — open an issue at https://github.com/khwstolle/ptwm/issues with a minimal reproducer (Python code or ptwm CLI invocation), the PTWM version (python -c "import ptwm; print(ptwm.__version__)"), the PyTorch version, and the platform.
• Security vulnerabilities — do not open a public issue. See SECURITY.md in the repository for the responsible-disclosure contact.
• Patent concerns — report via the same SECURITY.md contact.

Development setup

The dev environment lives in pyproject.toml + uv.lock, driven by uv. Nix is optional — a reproducible convenience, not a requirement.

# With Nix
nix develop

# Without Nix
uv sync --dev
source .venv/bin/activate

You need a working Rust toolchain (rustc, cargo) — the build compiles the ptwm._core native extension locally.

Pre-commit hooks

Prek manages the pre-commit hooks:

uv tool install prek
prek install                              # writes .git/hooks/pre-commit
nix develop -c prek run --all-files       # run the whole hook set

The hooks auto-fix what they can (ruff check --fix, ruff format, cargo fmt, hygiene hooks). If a hook rewrites files, the commit fails; re-stage and re-commit:

git add -u && git commit -m '...'

Do not pass --no-verify. If a hook flags something the auto-fixer can't fix (e.g. cargo clippy -D warnings), fix the underlying issue and re-stage.

Tests

uv run pytest                # Python test suite
cargo test --workspace       # Rust roundtrip + unit tests

The Python suite enforces --doctest-modules and a coverage floor of 75 %. The integration marker gates integration tests (pytest -m integration).

Pull requests

• Keep PRs focused — one concern per PR reviews and reverts cleanly.
• Follow the existing code style. Don't introduce new abstractions or generic helpers unless the use case is concrete.
• Add tests for new behaviour. Round-trip tests are the standard invariant for any codec or transform change.
• Update CHANGELOG.md under the unreleased section for any user-visible change.
• Don't commit secrets, .env files, or large binary artifacts.

By contributing, you agree to license your contributions under the MIT License.