# Contributing to ComfyUI-HyMT2

Thanks for your interest in ComfyUI-HyMT2! This file documents the
conventions and gotchas that aren't obvious from the code.

## Reporting bugs

Please use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md).
The most useful single piece of information is the startup banner from
ComfyUI's log:

```bash
grep "ComfyUI-HyMT2" /path/to/comfy.log
```

If the banner is missing, the pack didn't load — that's a different problem
than "the nodes don't work right".

## Development setup

```bash
git clone https://github.com/aadebuger/ComfyUI-HyMT2.git
cd ComfyUI-HyMT2

# Offline tests don't need torch / transformers / accelerate
pip install pytest websocket-client
pytest tests/ -v
```

Expected: **39 passed in <1s**.

For full integration testing (with a real model), drop the repo into
`ComfyUI/custom_nodes/` and run `scripts/install_deps.sh` to install
runtime dependencies.

## Pull request guidelines

### Style

- Match the existing `[hymt2/...]` log-prefix style. Production debugging
  relies on `grep -E "ComfyUI-HyMT2|hymt2"` to find every relevant line.
- Keep the `print(banner, flush=True)` lines at the top of every
  `nodes/*.py` module — they make production debugging much faster.
- Prefer pure-stdlib code in the CLI scripts. The only allowed third-party
  client dependency is `websocket-client`.

### Don't pin torch

**Never add `torch` to `pyproject.toml` `dependencies`.** ComfyUI's venv
already ships the correct torch build, and pinning it here makes
`uv pip install` rebuild a separate torch from PyPI — see
[INSTALL_NOTES.md](INSTALL_NOTES.md) for the war story.

### Defensive imports

The top-level `__init__.py` wraps node imports in `try/except`. If a
contributor adds a new node, make sure the import path is also under that
guard, so missing runtime dependencies don't take down ComfyUI startup.

### CLI changes

The CLI's `ComfyClient.run()` is the most subtle code in the package —
it's the result of three rounds of debugging real ComfyUI WebSocket
protocol drift (see [CHANGELOG](CHANGELOG.md) v0.1.1 and v0.1.2). Before
modifying it:

1. Read the existing tests under `tests/test_cli_protocol.py`.
2. If you're changing behavior, add a new scripted-WS test that captures
   the scenario.
3. Don't break the three confirmed-working paths: cached prompt, cold
   load, legacy `executing/node=null`.

### Documentation

For new features:

- Add an example workflow under `example_workflows/` (API format).
- Add a CLI flag if it deserves one.
- Update README's *Nodes* / *Prompt templates* / *Languages* tables.
- Add a CHANGELOG entry under the next `[Unreleased]` heading.

## Release process

1. Bump version in:
   - `__init__.py` (`__version__`)
   - `pyproject.toml` (`version`)
   - `nodes/runtime.py`, `nodes/loader.py`, `nodes/translate.py` (banners)
   - `README.md` (badge + banner-expected line)
2. Move `[Unreleased]` notes into a dated `[X.Y.Z]` heading in
   `CHANGELOG.md`.
3. Run `pytest tests/ -v` — must be all green.
4. Tag `vX.Y.Z` and push.

## Code of conduct

Be kind, be specific, be patient. This is a small project — no formal CoC
yet. Behave like you would on a friend's repo.