Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
150 lines (102 loc) · 6.86 KB

CONTRIBUTING.md

File metadata and controls

150 lines (102 loc) · 6.86 KB

Contributing

PRs are welcome and encouraged. This project is actively developed — if you have a bug fix, new feature, or quality improvement in mind, open an issue to discuss it first (for larger changes) or just submit a PR directly (for clear-cut fixes). The maintainer responds promptly.

Quick orientation

Before diving in, read these files in the repo root:

File What it covers
README.md What the project does, how the three nodes connect, and user-facing features
ProjectStructure.md Every file's purpose, all API routes with line numbers, data shapes, communication patterns, dependency graph, and 28 development gotchas
AI-CONTEXT.md Internal dev notes: architecture layers, critical codepaths, field naming rules, config data flow, common tasks

Dev setup

Requirements:

  • ComfyUI 0.12.3 or newer
  • Python 3.10+ (whatever version your ComfyUI install uses)

Install:

ComfyUI/custom_nodes/
└── ComfyUI-Ultimate-Auto-Sampler-Config-Grid-Testing-Suite/  ← clone here

Clone into ComfyUI/custom_nodes/ and restart ComfyUI. The node will register itself automatically.

Python dependencies:

pip install -r requirements.txt

requirements.txt currently pulls in diffusers and piexif. ComfyUI itself provides PyTorch, numpy, and Pillow.

Running tests

python -m pytest tests/ -v

There are currently 46 tests covering:

  • LTX video config expansion and cache key logic
  • Sigma parser
  • Config expansion (Cartesian products)
  • state_to_configs_json transformer

PRs that change Python logic should add tests where it's reasonable to do so.

JS syntax check

The Builder UI and Dashboard are plain JavaScript (no build step). You can catch syntax errors quickly with Node:

cd web/conf_builder
node --check conf-builder-main.js
node --check conf-builder-config-management.js
node --check conf-builder-utilities.js
node --check conf-builder-ui-components.js
node --check conf-builder-distribution.js

The dashboard JS files can also be checked the same way:

cd resources
node --check logic_utils.js
node --check logic_ui.js
node --check logic_virtual.js
node --check logic_pipeline.js
node --check logic_events.js
node --check logic_init.js
node --check logic_state.js

Architecture notes worth knowing before editing

The Builder UI is a DOM widget on the Python node. Its entire state is serialized to a single lora_config STRING widget as JSON. Python's generate_config() reads only that widget — all other INPUT_TYPES entries are vestigial.

State → configs_json transformation: All state-to-output transformation logic lives in state_to_configs_json (a @staticmethod on UltimateConfigBuilder in config_builder_node.py, around line 524). Both runtime (generate_config, line ~837) and the preview endpoint (POST /configbuilder/preview) call this single function. Do not add a JS-side equivalent transformer — that pattern existed historically (convertStateToConfigs) and was a recurring source of drift bugs; it was deliberately removed in favor of the single source of truth in Python.

When adding a new state field that should appear in configs_json:

  1. Add the field to state_to_configs_json in config_builder_node.py. Make sure tests in tests/test_state_to_configs_json.py cover the new field.
  2. Update the Builder UI in web/conf_builder/conf-builder-config-management.js to read/write the field via node.state.<field>. Also add the default in the initial state object in conf-builder-main.js (search for this.state = {, around line 103), and add a migration backfill in the async init block below it (conf-builder-main.js, around line 484) so existing saved workflows pick up the default.
  3. The preview panel will pick up the new field automatically — it just renders whatever state_to_configs_json returns.

Manifest field names — check before touching favorite/reject logic:

  • favorited (not favorite) — used in __init__.py routes
  • note (not notes) — per-item annotation
  • file — full /view?... URL, not a filename
  • rejected — required boolean for dashboard display
  • id — timestamp-based integer: int(time.time() * 100000) + random.randint(0, 1000)

Manifest items are inserted at index 0 (newest-first order).

ComfyUI V3 vs V1 nodes: Use the _call_node and _unwrap helpers when calling V3 nodes outside the executor pipeline. See ltx_video_generation.py for the established pattern.

Windows print safety: Two modules (config_builder_node.py, ltx_video_generation.py) shadow print with safe_print at module level (print = safe_print) to avoid colorama/stdout corruption that throws OSError [Errno 22] on long-running sessions. If you add new print-heavy code in those files, use the existing print = safe_print shadow at module top. Other modules use bare print() directly.

Distributed mode exists. Workers consume the already-rendered configs_json over the wire. Don't assume single-machine execution in generation orchestrator code.

ComfyUI Registry security constraints (violations get the version flagged and hidden from Manager):

  • No import requests — use urllib.request (stdlib)
  • No subprocess, os.system, eval(), or exec()
  • No runtime pip install
  • No custom file-serving endpoints — use ComfyUI's /view endpoint for images and WEB_DIRECTORY for JS
  • All filesystem endpoints must validate paths with _is_path_within() and sanitize user-supplied names

Dashboard JS changes require HTML regeneration. The resources/ files are inlined into a single HTML string by html_generator.py. After editing dashboard JS/CSS, you must re-run the sampler node or call POST /config_tester/get_session_html to see the changes. Browser refresh alone is not enough.

PR checklist

Before submitting:

  • python -m pytest tests/ -v passes
  • JS syntax checks pass (node --check on changed files)
  • No regressions in existing features
  • For new config fields: state_to_configs_json updated in Python, default state and migration backfill added in conf-builder-main.js, and UI read/write added in conf-builder-config-management.js
  • For user-facing features: README.md updated
  • For Builder UI or Dashboard changes: smoke-tested in real ComfyUI (unit tests alone are not sufficient here)
  • No new import requests, subprocess, os.system, eval, or exec calls (Registry security)

Where to discuss

  • Bugs and feature requests: GitHub Issues
  • Code changes: GitHub Pull Requests

The maintainer (Jason Hoku) actively monitors both.

License

This project is open source. The license is declared in pyproject.toml (license = {file = "LICENSE"}). A LICENSE file is referenced there but not yet present in the repo root — check the GitHub repository page for the current license terms.