101 lines
4.0 KiB
Markdown
101 lines
4.0 KiB
Markdown
# 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.
|