From 5a4ad06c19ac3fdc2e070b77386e78fd28d01d8e Mon Sep 17 00:00:00 2001 From: bymyself Date: Wed, 6 Aug 2025 16:55:17 -0700 Subject: [PATCH 1/4] [docs] Add backporting workflow documentation - Explain the automated backport process with real example - Use PR #4616 (subgraph bugfix) as concrete example - Include step-by-step instructions for developers - Clarify when backporting is appropriate (bug fixes vs features) --- README.md | 39 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 37 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index fffd56c1e7..a432416187 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,6 @@ **Official front-end implementation of [ComfyUI](https://github.com/comfyanonymous/ComfyUI).** - - [![Website][website-shield]][website-url] [![Discord][discord-shield]][discord-url] [![Matrix][matrix-shield]][matrix-url] @@ -530,6 +528,43 @@ Have another idea? Drop into Discord or open an issue, and let's chat! We document significant architectural decisions using ADRs (Architecture Decision Records). See [docs/adr/](docs/adr/) for all ADRs and the template for creating new ones. +### Backporting Changes to Release Branches + +When you fix a bug that affects a version in feature freeze, we use an automated backport process to apply the fix to the release candidate branch. + +**Real example:** +- Subgraphs feature was released in v1.24 +- While developing v1.25, we discovered a bug in subgraphs +- v1.24 is in feature freeze (only accepting bug fixes, no new features) +- The fix needs to be applied to both main (v1.25) and the v1.24 release candidate + +**How to backport your fix:** + +1. Create your PR fixing the bug on `main` branch as usual +2. Before merging, add these labels to your PR: + - `needs-backport` - triggers the automated backport workflow + - `1.24` - targets the `core/1.24` release candidate branch + +3. Merge your PR normally +4. The automated workflow will: + - Create a new branch from `core/1.24` + - Apply your changes to that branch + - Open a new PR to `core/1.24` + - Comment on your original PR with a link to the backport PR + +**When to use backporting:** +- Bug fixes for features already released +- Security fixes +- Critical issues affecting existing functionality +- Never for new features (these wait for the next release cycle) + +**Handling conflicts:** +If the automated cherry-pick fails due to conflicts, the workflow will comment on your PR with: +- The list of conflicting files +- Instructions to manually cherry-pick to the release candidate branch + +See [PR #4616](https://github.com/Comfy-Org/ComfyUI_frontend/pull/4616) for the actual subgraph bugfix that was backported from v1.25 to v1.24. + ## Development ### Prerequisites & Technology Stack From 42c0194495d4766fc073e6783ca62038658f841e Mon Sep 17 00:00:00 2001 From: bymyself Date: Wed, 6 Aug 2025 17:34:45 -0700 Subject: [PATCH 2/4] [docs] Move contributing and development info to CONTRIBUTING.md - Create comprehensive CONTRIBUTING.md with all development information - Move contributing guidelines, development setup, and testing info from README - Add backporting workflow documentation with real example (PR #4616) - Keep README focused on project overview and usage - Maintain all existing content, just better organized --- CONTRIBUTING.md | 278 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 236 ++-------------------------------------- 2 files changed, 286 insertions(+), 228 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..c632bfad5f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,278 @@ +# Contributing to ComfyUI Frontend + +We're building this frontend together and would love your help — no matter how you'd like to pitch in! You don't need to write code to make a difference. + +## Ways to Contribute + +- **Pull Requests:** Add features, fix bugs, or improve code health. Browse [issues](https://github.com/Comfy-Org/ComfyUI_frontend/issues) for inspiration. +- **Vote on Features:** Give a 👍 to the feature requests you care about to help us prioritize. +- **Verify Bugs:** Try reproducing reported issues and share your results (even if the bug doesn't occur!). +- **Community Support:** Hop into our [Discord](https://www.comfy.org/discord) to answer questions or get help. +- **Share & Advocate:** Tell your friends, tweet about us, or share tips to support the project. + +Have another idea? Drop into Discord or open an issue, and let's chat! + +## Development Setup + +### Prerequisites & Technology Stack + +- **Required Software**: + - Node.js (v16 or later; v20/v22 strongly recommended) and npm + - Git for version control + - A running ComfyUI backend instance + +- **Tech Stack**: + - [Vue 3](https://vuejs.org/) with [TypeScript](https://www.typescriptlang.org/) + - [Pinia](https://pinia.vuejs.org/) for state management + - [PrimeVue](https://primevue.org/) with [TailwindCSS](https://tailwindcss.com/) for UI + - [litegraph.js](https://github.com/Comfy-Org/litegraph.js) for node editor + - [zod](https://zod.dev/) for schema validation + - [vue-i18n](https://github.com/intlify/vue-i18n) for internationalization + +### Initial Setup + +1. Clone the repository: + ```bash + git clone https://github.com/Comfy-Org/ComfyUI_frontend.git + cd ComfyUI_frontend + ``` + +2. Install dependencies: + ```bash + npm install + ``` + +3. Configure environment (optional): + Create a `.env` file in the project root based on the provided [.env.example](.env.example) file. + + **Note about ports**: By default, the dev server expects the ComfyUI backend at `localhost:8188`. If your ComfyUI instance runs on a different port, update this in your `.env` file. + +### Dev Server Configuration + +To launch ComfyUI and have it connect to your development server: + +```bash +python main.py --port 8188 +``` + +### Git pre-commit hooks + +Run `npm run prepare` to install Git pre-commit hooks. Currently, the pre-commit hook is used to auto-format code on commit. + +### Dev Server + +Note: The dev server will NOT load any extension from the ComfyUI server. Only core extensions will be loaded. + +- Start local ComfyUI backend at `localhost:8188` +- Run `npm run dev` to start the dev server +- Run `npm run dev:electron` to start the dev server with electron API mocked + +#### Access dev server on touch devices + +Enable remote access to the dev server by setting `VITE_REMOTE_DEV` in `.env` to `true`. + +After you start the dev server, you should see following logs: + +``` +> comfyui-frontend@1.3.42 dev +> vite + + + VITE v5.4.6 ready in 488 ms + + ➜ Local: http://localhost:5173/ + ➜ Network: http://172.21.80.1:5173/ + ➜ Network: http://192.168.2.20:5173/ + ➜ press h + enter to show help +``` + +Make sure your desktop machine and touch device are on the same network. On your touch device, +navigate to `http://:5173` (e.g. `http://192.168.2.20:5173` here), to access the ComfyUI frontend. + +## Development Workflow + +### Architecture Decision Records + +We document significant architectural decisions using ADRs (Architecture Decision Records). See [docs/adr/](docs/adr/) for all ADRs and the template for creating new ones. + +### Backporting Changes to Release Branches + +When you fix a bug that affects a version in feature freeze, we use an automated backport process to apply the fix to the release candidate branch. + +#### Real Example + +- Subgraphs feature was released in v1.24 +- While developing v1.25, we discovered a bug in subgraphs +- v1.24 is in feature freeze (only accepting bug fixes, no new features) +- The fix needs to be applied to both main (v1.25) and the v1.24 release candidate + +#### How to Backport Your Fix + +1. Create your PR fixing the bug on `main` branch as usual +2. Before merging, add these labels to your PR: + - `needs-backport` - triggers the automated backport workflow + - `1.24` - targets the `core/1.24` release candidate branch + +3. Merge your PR normally +4. The automated workflow will: + - Create a new branch from `core/1.24` + - Apply your changes to that branch + - Open a new PR to `core/1.24` + - Comment on your original PR with a link to the backport PR + +#### When to Use Backporting + +- Bug fixes for features already released +- Security fixes +- Critical issues affecting existing functionality +- Never for new features (these wait for the next release cycle) + +#### Handling Conflicts + +If the automated cherry-pick fails due to conflicts, the workflow will comment on your PR with: +- The list of conflicting files +- Instructions to manually cherry-pick to the release candidate branch + +See [PR #4616](https://github.com/Comfy-Org/ComfyUI_frontend/pull/4616) for the actual subgraph bugfix that was backported from v1.25 to v1.24. + +## Code Editor Configuration + +### Recommended Setup + +This project includes `.vscode/launch.json.default` and `.vscode/settings.json.default` files with recommended launch and workspace settings for editors that use the `.vscode` directory (e.g., VS Code, Cursor, etc.). + +We've also included a list of recommended extensions in `.vscode/extensions.json`. Your editor should detect this file and show a human friendly list in the Extensions panel, linking each entry to its marketplace page. + +### MCP Integrations + +#### Playwright Browser Automation + +The Playwright MCP server enables LLM coding assistants (like Copilot, Claude Code, etc.) to control and inspect web browsers programmatically. This allows assistants to navigate websites, take screenshots, and interact with web pages on your behalf. + +For ComfyUI_frontend development, you can ask coding assistants to use Playwright screenshots to continuously verify that your code changes produce the expected visual results. + +##### Setup for Claude Code + +After installing dependencies with `npm i`, the Playwright MCP server will be automatically available when you start Claude Code locally. + +## Testing + +### Unit Tests + +- `npm i` to install all dependencies +- `npm run test:unit` to execute all unit tests + +### Component Tests + +Component tests verify Vue components in `src/components/`. + +- `npm run test:component` to execute all component tests + +### Playwright Tests + +Playwright tests verify the whole app. See [browser_tests/README.md](browser_tests/README.md) for details. + +### Running All Tests + +Before submitting a PR, ensure all tests pass: + +```bash +npm run test:unit +npm run test:component +npm run test:browser +npm run typecheck +npm run lint +npm run format +``` + +## Code Style Guidelines + +### TypeScript +- Use TypeScript for all new code +- Avoid `any` types - use proper type definitions +- Never use `@ts-expect-error` - fix the underlying type issue + +### Vue 3 Patterns +- Use Composition API for all components +- Follow Vue 3.5+ patterns (props destructuring is reactive) +- Use `