# Contributing

Focused fixes, workflow improvements, compatibility updates, and documentation
corrections are welcome. Open an issue before a large redesign so its runtime
and saved-workflow compatibility can be discussed first.

## Keep version 0.5 compatible

Version 0.5 preserves saved 0.4 workflows and checkpoints. Unless a change is
explicitly planned as a breaking release:

- do not reuse or rename an existing public node class ID;
- do not reorder existing positional inputs or outputs;
- append new optional inputs and outputs instead of inserting them;
- retain readable legacy widget values and checkpoint formats;
- keep compatible H3-Multishot, SolAttn, and shared patch markers intact.

The frozen rules are documented in
[Version 0.5 architecture](docs/V0_5_ARCHITECTURE.md) and enforced by
`tests/fixtures/v0_4_public_contract.json`.

## Document behavior from evidence

Use the implementation, tests, maintained workflows, and upstream source as
the authority. A user-facing claim should point to a working example or a
specific implementation path. Mark experiments as experimental and describe
their fallback or compatibility behavior.

When a change is derived from another project, update
[Feature traceability](docs/FEATURE_TRACEABILITY.md) and
[Third-party notices](THIRD_PARTY_NOTICES.md) together. Record:

1. the upstream repository and author;
2. the revision or pull request used;
3. the upstream license;
4. the local files that implement the feature;
5. whether the relationship is **adapted**, **inspired**, **integrated**, or
   **compatibility-only**.

Do not describe an integration with an upstream API as copied code, and do not
describe an adaptation as an original implementation.

## Validate a change

Run the focused test for the area you changed. Before release or a broad pull
request, run at least:

```bash
python tests/_node_smoke_test.py
python tests/_chain_smoke_test.py
python tests/_workflow_catalog_unit_test.py
python tests/_v05_contract_unit_test.py
```

Masking, source-timeline, frontend, and migration changes have additional
targeted scripts under `tests/`. JavaScript tests use Node directly, for
example:

```bash
node tests/_plan_editor_js_test.mjs
```

Tests intentionally use mock ComfyUI modules where possible. Real generation
still needs a current ComfyUI installation, H3 models, and appropriate media.

## Keep the README approachable

The README is a workflow chooser and quick start. Put algorithms, complete
node settings, and recovery internals in the focused guides under `docs/`.
Prefer short tables, task-based headings, and links to deeper explanations.

When adding or retiring a maintained workflow, update
`example_workflows/README.md` and `tests/_workflow_catalog_unit_test.py` in the
same change. Keep prompt and media attribution beside the workflow that uses
it.