Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
74 lines (49 loc) · 3.12 KB

CONTRIBUTING.md

File metadata and controls

74 lines (49 loc) · 3.12 KB

Contributing to CorridorKey

Thanks for your interest in improving CorridorKey! Whether you're a VFX artist, a pipeline TD, or a machine learning researcher, contributions of all kinds are welcome — bug reports, feature ideas, documentation fixes, and code.

Getting Started

Prerequisites

  • Python 3.10 or newer
  • uv for dependency management

Dev Setup

git clone https://github.com/nikopueringer/CorridorKey.git
cd CorridorKey
uv sync --group dev    # installs all dependencies + dev tools (pytest, ruff)

That's it. No manual virtualenv creation, no pip install — uv handles everything.

Running Tests

uv run pytest              # run all tests
uv run pytest -v           # verbose (shows each test name)
uv run pytest -m "not gpu" # skip tests that need a CUDA GPU
uv run pytest --cov        # show test coverage (sources and branch mode configured in pyproject.toml)

Most tests run in a few seconds and don't need a GPU or model weights. Tests that require CUDA are marked with @pytest.mark.gpu and will be skipped automatically if no GPU is available.

Linting and Formatting

uv run ruff check          # check for lint errors
uv run ruff format --check # check formatting (no changes)
uv run ruff format         # auto-format your code

CI runs both checks on every pull request. Running them locally before pushing saves a round-trip.

Making Changes

Pull Requests

  1. Fork the repo and create a branch for your change
  2. Make your changes
  3. Run uv run pytest and uv run ruff check to make sure everything passes
  4. Open a pull request against main

In your PR description, focus on why you made the change, not just what changed. If you're fixing a bug, describe the symptoms. If you're adding a feature, explain the use case. A couple of sentences is plenty.

What Makes a Good Contribution

  • Bug fixes — especially for edge cases in EXR/linear workflows, color space handling, or platform-specific issues
  • Tests — more test coverage is always welcome, particularly for clip_manager.py and inference_engine.py
  • Documentation — better explanations, usage examples, or clarifying comments in tricky code
  • Performance — reducing GPU memory usage, speeding up frame processing, or optimizing I/O

Code Style

  • The project uses ruff for both linting and formatting
  • Lint rules: E, F, W, I, B (basic style, unused imports, import sorting, common bug patterns)
  • Line length: 120 characters
  • Third-party code in gvm_core/ and VideoMaMaInferenceModule/ is excluded from lint enforcement — those are derived from research repos and we try to keep them close to upstream

Model Weights

The model checkpoint (CorridorKey_v1.0.pth) and optional GVM/VideoMaMa weights are not in the git repo. Most tests don't need them. If you're working on inference code and need the weights, follow the download instructions in the README.

Questions?

Join the Discord — it's the fastest way to get help or discuss ideas before opening a PR.