120 lines
5.2 KiB
Markdown
120 lines
5.2 KiB
Markdown
# Contributing
|
|
|
|
Thanks for helping improve ComfyUI-Doctor. This project is a ComfyUI custom node, so changes must preserve both normal Python package behavior and ComfyUI host-loading behavior.
|
|
|
|
## Before You Start
|
|
|
|
Required local tools:
|
|
|
|
- Python 3.10 or newer
|
|
- Node.js `>=18 <26`
|
|
- npm 9 or newer
|
|
- Git
|
|
|
|
Recommended local setup:
|
|
|
|
```powershell
|
|
python -m venv .venv
|
|
.\.venv\Scripts\Activate.ps1
|
|
python -m pip install -r requirements-dev.txt
|
|
npm install
|
|
```
|
|
|
|
Use one Python interpreter consistently for setup, tests, and validation. On Windows, the repository full-test script uses `.venv` as the project-local environment.
|
|
|
|
Use Node.js 24 for the current Vitest unit-test dependency stack. The broader Node.js 18 through 25
|
|
range above describes the frontend E2E harness; it is not a compatibility claim for every dev tool.
|
|
|
|
## Repository Orientation
|
|
|
|
Start with these public docs:
|
|
|
|
- [Architecture](docs/ARCHITECTURE.md) for package startup, backend services, frontend modules, security boundaries, and test lanes.
|
|
- [API reference](docs/API_REFERENCE.md) and [OpenAPI contract](docs/openapi.json) for route-level behavior.
|
|
- [Validation guide](docs/VALIDATION.md) for supported validation workflows.
|
|
- [Configuration and security](docs/CONFIGURATION_SECURITY.md) for credential, admin, and deployment safety notes.
|
|
- [Outbound safety](docs/OUTBOUND_SAFETY.md) for network-boundary expectations.
|
|
|
|
Key source areas:
|
|
|
|
- `__init__.py`, `prestartup_script.py`, and `nodes.py` handle ComfyUI package loading.
|
|
- `api_routes.py` and `services/routes.py` register and implement HTTP routes.
|
|
- `services/llm/`, `services/security/`, `services/infra/`, and `services/community/` provide stable service-domain entry points.
|
|
- `web/` contains the ComfyUI browser extension, sidebar UI, Preact islands, and vanilla fallbacks.
|
|
- `tests/` contains backend, host-load, and Playwright coverage.
|
|
|
|
## Development Workflow
|
|
|
|
1. Keep changes scoped to the feature or fix.
|
|
2. Preserve existing compatibility boundaries unless the change explicitly updates them.
|
|
3. Add or update tests for the bug class or behavior being changed.
|
|
4. Keep public documentation synchronized when user-facing behavior, API routes, setup, or validation flow changes.
|
|
5. Run targeted tests first, then the full local gate before submitting a pull request.
|
|
|
|
For route changes, update `docs/openapi.json` and add or update route/spec drift coverage. For frontend changes, prefer user-visible assertions in Playwright over checks that only prove the page loaded.
|
|
|
|
## Testing Requirements
|
|
|
|
Follow the repository test SOPs in this order:
|
|
|
|
1. [Test SOP](tests/TEST_SOP.md)
|
|
2. [E2E testing notice](tests/E2E_TESTING_NOTICE.md)
|
|
3. [E2E testing SOP](tests/E2E_TESTING_SOP.md)
|
|
|
|
Preferred full local validation on Windows:
|
|
|
|
```powershell
|
|
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/run_full_tests_windows.ps1
|
|
```
|
|
|
|
Preferred full local validation on Linux or WSL:
|
|
|
|
```bash
|
|
bash scripts/run_full_tests_linux.sh
|
|
```
|
|
|
|
The full gate covers dependency safety checks, detect-secrets, pre-commit hooks, host-like package/startup validation, backend tests, and default Playwright E2E.
|
|
|
|
Supplemental lanes:
|
|
|
|
- `npm run test:integration` runs opt-in integration-tagged telemetry tests. It uses the Playwright harness backend by default unless `COMFYUI_URL` is set.
|
|
- `npm run test:stress` runs opt-in stress-tagged telemetry burst/state tests.
|
|
- `python scripts/focused_gate.py` runs focused security, contract, and regression checks. It supplements the full gate and does not replace it.
|
|
|
|
## Documentation Expectations
|
|
|
|
Documentation should be public-safe, user-oriented, and synchronized with behavior:
|
|
|
|
- Update architecture docs when module boundaries, startup behavior, test lanes, or compatibility assumptions change.
|
|
- Update API docs and OpenAPI when routes, methods, request payloads, response payloads, or admin requirements change.
|
|
- Update setup and validation docs when tooling, prerequisites, or command flows change.
|
|
- Keep examples free of real tokens, private URLs, private hostnames, local state paths, and user-specific data.
|
|
|
|
## Security and Privacy Boundaries
|
|
|
|
Never commit secrets, credentials, cookies, tokens, local state, generated reports, private host data, or workstation-specific files.
|
|
|
|
Security-sensitive changes should account for:
|
|
|
|
- admin-token enforcement on write-sensitive endpoints
|
|
- SSRF and private-network protections for outbound provider URLs
|
|
- outbound sanitization and privacy modes before remote LLM calls
|
|
- server-side credential storage behavior
|
|
- local-only telemetry expectations
|
|
- plugin trust scanning without importing third-party plugin code
|
|
|
|
If a change touches these boundaries, include focused tests for the failure mode and run the full validation gate.
|
|
|
|
## Pull Request Readiness
|
|
|
|
Before opening a pull request:
|
|
|
|
- Rebase or merge current upstream changes as appropriate for your branch.
|
|
- Confirm public docs match the behavior being submitted.
|
|
- Run targeted tests for the changed area.
|
|
- Run the full local validation gate.
|
|
- Review staged files to ensure only intended public-safe files are included.
|
|
- Use a concise Conventional Commit style subject for commits.
|
|
|
|
Keep pull requests narrow enough to review. When a change spans backend, frontend, tests, and docs, describe the user-visible behavior and the validation commands that passed.
|