aadebuger-ComfyUI-LensTurbo/CONTRIBUTING.md

Contributing to ComfyUI-LensTurbo

Thanks for your interest! Bug reports, model variant support, and PRs are all welcome.

Bug reports

When reporting a bug, please include:

1. The exact symptom — the error message (full traceback if possible) or the visual artifact.
2. offload_mode setting on LensTurboLoader.
3. Hardware — GPU model, VRAM, system RAM, OS.
4. Versions — pip freeze | grep -E "torch|diffusers|transformers|accelerate|huggingface_hub|kernels".
5. The relevant section of comfy.log — grep -E "ComfyUI-LensTurbo|lens-turbo|LensTurbo|OutOfMemory|Traceback" comfy.log | tail -50.

Check INSTALL_NOTES.md first — the L1–L10 pitfall library covers the issues seen during initial development.

Pull requests

Setup

git clone https://github.com/aadebuger/ComfyUI-LensTurbo
cd ComfyUI-LensTurbo
bash scripts/fetch_upstream.sh
bash scripts/install_deps.sh

Code style

• Match existing style; no enforced linter yet, but keep functions small and prefer composition over inheritance.
• Type hints encouraged for public APIs (loader / sampler inputs, runtime helpers).
• Diagnostic print(..., flush=True) is fine — it's how we trace what loaded and what didn't.
• Docstrings explain why, not what — the what should be obvious from the code.

Banners are not optional

Both __init__.py and nodes/__init__.py print banners to stdout AND stderr at import time. This is the only reliable way to know which copy of the pack ComfyUI actually loaded. If you add a new top-level module, follow the same pattern. See nodes/__init__.py for the template.

Adding a new offload mode

If you want to add e.g. offload_mode="dual_gpu_balanced":

1. Add the new mode to OFFLOAD_MODES in nodes/runtime.py.
2. Implement the branch in build_pipeline().
3. If it needs monkey-patches similar to _install_cpu_text_encoder_patches, write a standalone _install_<mode_name>_patches function so it can be reused by smoke-test scripts outside ComfyUI.
4. Add the choice to the LensTurboLoader.INPUT_TYPES enum and the CLI's --offload-mode choices.
5. Update example_workflows/lens_turbo_t2i.json, README, and CHANGELOG.

Testing changes

Before submitting:

1. Smoke test directly in Python (no ComfyUI) — this catches model-level bugs fast. See INSTALL_NOTES Verifying section.
2. End-to-end via CLI:

   python cli/lens_turbo_cli.py "a cat" --ip 127.0.0.1 --gpu 0 --steps 4
   

3. End-to-end via batch:

   python cli/lens_turbo_batch.py cli/example_vocab.json --ip 127.0.0.1 --gpu 0 --out-dir ./test_out
   

4. Document the change in CHANGELOG.md under a new [Unreleased] section (move to a version on release).

Commit messages

Conventional commits encouraged but not required:

• feat: add dual_gpu_balanced offload mode
• fix: handle empty negative_prompt at CFG=1.0
• docs: clarify HF_HOME setup in README
• chore: bump diffusers floor to 0.33

What we won't merge

• Removal of the banners — they're a deliberate debugging aid for .bak-shadow scenarios.
• Hardcoded paths to /mnt/modelall/ or similar — those are deployment-specific; use env vars (HF_HOME, TMPDIR).
• Re-introducing enable_sequential_cpu_offload as a recommended mode — broken on accelerate ≥1.x. Kept for completeness only.
• Bundling model weights — these are gated and large, users download from HF themselves.

Releasing (for maintainers)

# 1. Update version
sed -i 's/version = "X.Y.Z"/version = "X.Y+1.0"/' pyproject.toml
sed -i 's/__version__ = "X.Y.Z"/__version__ = "X.Y+1.0"/' __init__.py

# 2. Add CHANGELOG entry above the previous version

# 3. Commit + tag
git add -A
git commit -m "release: v0.X.Y"
git tag v0.X.Y
git push && git push --tags

# 4. GitHub Release: copy CHANGELOG section into release notes

Questions?

Open an issue with the question label, or check the README's Troubleshooting section first.