# 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](INSTALL_NOTES.md) first — the L1–L10 pitfall library covers the issues seen during initial development.

## Pull requests

### Setup

```bash
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](INSTALL_NOTES.md#verifying-the-cpu_text_encoder-patches-fire).
2. **End-to-end via CLI**:
   ```bash
   python cli/lens_turbo_cli.py "a cat" --ip 127.0.0.1 --gpu 0 --steps 4
   ```
3. **End-to-end via batch**:
   ```bash
   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)

```bash
# 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](README.md#troubleshooting) section first.