Skip to content

Contributing to renewable-huber

Thanks for helping improve robust streaming regression. Bug reports, reproducible performance results, documentation fixes, and focused code contributions are welcome.

Before opening an issue

  • Search existing issues and pull requests.
  • Use the bug or feature template and include the smallest reproducible example.
  • Do not publish security vulnerabilities in an issue; follow SECURITY.md.
  • For performance reports, include OS, Python version, backend, dtype, array shape, hardware, dependency versions, warm-up policy, and benchmark command.

Development setup

WSL2/Linux is the primary native-core development environment. Bootstrap a new WSL checkout with one of the declared profiles:

bash scripts/setup-wsl-toolchain.sh             # add --cuda for CUDA 12
bash scripts/setup-wsl-venv.sh --profile minimal
# or: cpu-full / cuda-full

minimal covers the base package and native CPU extension. cpu-full also installs pandas, SciPy, scikit-learn, PyTorch and TensorFlow. cuda-full adds CuPy, builds the native CUDA extension and fails verification when WSL GPU passthrough is unavailable. scripts/verify_wsl_environment.py reports every required component explicitly; an unavailable integration must never be mistaken for a fully passing suite.

The PowerShell setup below remains supported for Windows-only work.

Create an isolated environment with Python 3.10–3.13:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev,sklearn,pandas]"

Install only the optional compute framework you need. CUDA tests require compatible NVIDIA drivers and the CuPy CUDA 12 extra:

python -m pip install -e ".[dev,gpu-cupy]"

Validation

Run the checks relevant to the change before opening a pull request:

.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python -m ruff check src tests scripts
.venv/bin/python -m ruff format --check src tests scripts
.venv/bin/python -m mypy                      # settings in [tool.mypy]
.venv/bin/python -m coverage run scripts/run_test_profile.py core
.venv/bin/python -m coverage report           # enforces fail_under
.venv/bin/python scripts/native/validate_release_artifacts.py --source-only
.venv/bin/python scripts/generate_native_golden.py --check
.venv/bin/python -m build

g++ -std=c++17 -fsyntax-only -I native/cuda/include native/cuda/src/abi_contract.cpp
(
  cd native
  cargo fmt --all -- --check
  cargo clippy --locked --workspace --all-targets -- -D warnings
  cargo check --locked --workspace --all-targets
  cargo test --locked -p rh-core -p rh-cpu -p rh-cuda-ffi --all-targets
)

fail_under in [tool.coverage.report] is the core profile's line+branch coverage in a clean pip install ".[dev]" environment (73.2% when set), rounded down, less one point; CI measures it the same way in the quality job. An installed native extension or optional framework tends to raise the local figure. The Rust property tests in rh-core/tests/properties.rs and rh-cpu/src/proptests.rs run a modest number of cases; set PROPTEST_CASES for a longer local soak (in --release if it includes the large-batch cases).

discover remains supported and is the quickest local pass. It is tolerant by design: a suite whose dependency or device is missing reports success as a set of skips. For anything that has to prove it ran, use a named profile:

.venv/bin/python scripts/run_test_profile.py --list
.venv/bin/python scripts/run_test_profile.py --check
.venv/bin/python scripts/run_test_profile.py core --verbose
.venv/bin/python scripts/run_test_profile.py performance --verbose
.venv/bin/python scripts/run_test_profile.py all --verbose

core, optional-cpu, native-cpu, cuda and performance are required profiles: each probes its declared dependency or device first and exits with status 2 when one is missing, so a green result cannot be an empty one. all is the developer default and keeps its documented optional skips. GPU work uses the cuda profile on the fixed local host; it must not run in GitHub Actions. Adding a test module without assigning it to a profile fails --check.

optional-cpu is CPU-only by definition and enforces it: the runner sets CUDA_VISIBLE_DEVICES="" for that profile and restores the previous value afterwards. PyTorch and TensorFlow each initialise their own CUDA runtime in one process, and on a machine with a GPU the second one to do so can fail (cusolverDnCreate returning CUSOLVER_STATUS_INTERNAL_ERROR), which would make the profile's result depend on import order. No other profile forces any environment, so cuda still sees the device. run_test_profile.py --list prints the forced variables.

Backend-specific changes must include parity tests against NumPy. Performance changes must include correctness tests and reproducible before/after benchmark output; a faster result is not accepted if it changes the documented numerical contract.

Documentation site

The English documentation site is built with MkDocs Material from mkdocs.yml and docs/. Preview it locally from the repository root:

python -m pip install -e ".[docs]" && mkdocs serve
mkdocs build --strict    # what CI runs

Pull requests run mkdocs build --strict (.github/workflows/docs.yml), which fails on a broken link or anchor. The home page and user guide include marked regions of README.en.md, so edit the README there rather than copying text into docs/, and keep relative links out of those regions. Links from docs/ to files outside it use absolute GitHub URLs. Existing documents keep their language and file names, because the READMEs, AGENTS.md, the changelog and scripts link to them.

Pull requests

  • Branch from the latest main and keep the change focused.
  • Add or update tests and public documentation with code changes.
  • Update CHANGELOG.md under Unreleased for user-visible behavior.
  • Do not commit datasets, model files, generated build artifacts, research PDFs, credentials, or local benchmark output.
  • Let CI pass on all required CPU platforms. Run GPU correctness, CUDA smoke, profiling, and performance gates locally on the fixed GPU host; GPU validation must not run in GitHub Actions for pull requests. Record the exact commit, the environment (GPU, driver, CUDA runtime) and the machine-readable gate output with the pull request.
  • Use Conventional Commit-style imperative subjects when practical, for example perf: fuse CUDA renewal kernels.

The main branch requires a pull request, an up-to-date branch, all cross-platform and optional CPU integration checks, package smoke tests, and resolved review conversations. Force pushes and branch deletion are disabled. These rules live in the repository's branch protection settings.

Unless explicitly marked otherwise, contributions intentionally submitted for inclusion are distributed under the Apache License, Version 2.0, as described in section 5 of that license.