Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Contributing to OpenDefocus

Contributing to OpenDefocus is greatly appreciated and welcome!

How work is organised

Work is driven by GitHub issues.

  1. Pick an open issue, or open one with the Task or Bug report template. A task describes the goal, context, scope, acceptance criteria and how to verify it, so anyone can pick it up. Comment on the issue before you start so work is not duplicated.
  2. Work on a branch named <type>/<issue>-<slug>, for example fix/142-roi-padding.
  3. Open a pull request against main that says Closes #<issue> and shows how each acceptance criterion was verified.

Report security vulnerabilities privately, as described in SECURITY.md.

Development

Working with coding agents

Agents start at AGENTS.md, which links to ARCHITECTURE.md, TESTING.md and SECURITY.md. Keep personal agent settings out of Git.

Tools Required

Install only the tools needed for your task:

TaskAdditional tools beyond stable Rust 1.95+ and native linker/build tools
Library, CLI or viewerNothing beyond stable Rust 1.95+ and native linker/build tools
Validate authored GPU shaderscargo xtask --compile --gpu uses Naga on stable Rust. Shader changes also need hardware correctness and performance checks. The excluded historical SPIR-V utility alone uses its pinned nightly.
Python tests and checksuv; each Python crate under crates/ manages its own environment.
Contributor pre-commit hooksRun uvx pre-commit run --all-files; the hook runs cargo xtask --precommit, which uses uvx for ty and validates shaders when kernel files change.
Build or serve documentationcargo install --locked cargo-about mdbook mdbook-toc
Browser viewerrustup target add wasm32-unknown-unknown, then cargo install --locked wasm-bindgen-cli --version 0.2.129; build with cargo xtask --compile --web.
OpenFX plugin bundleNothing beyond stable Rust 1.95+ and native linker/build tools; build with cargo xtask --bundle-ofx.

A normal CLI build is cargo xtask --compile --cli; a viewer build is cargo xtask --compile --ui. Neither requires Python tooling or nightly Rust. Avoid installing the documentation tools unless you work on documentation.

Checks before a pull request

Run cargo fmt --all -- --check and cargo xtask --test-crates for Rust changes. Use cargo xtask --compile --gpu for shader validation; hardware changes also need the correctness and performance checks in TESTING.md.

The imported Python crates in crates/ have their own environments, test commands, and CI.

Getting Started

  1. Fork the repository to your GitHub account.

    git clone git@github.com:YOUR_USERNAME/opendefocus.git
    cd opendefocus/
    
  2. Create a branch for the issue, for example fix/142-roi-padding.

  3. Commit using the conventional commits specifications

  4. Run the development environment. Everything is handled through the xtask.

  5. Create your contribution and test the changes.


Most of all

Thank you!! For taking the time to read this and to contribute your time into this project.