From ca41e240abdc16e4a4b5f0c00fc57f97782a942e Mon Sep 17 00:00:00 2001 From: Berry Wahlberg <40695099+BerryUIKI@users.noreply.github.com> Date: Wed, 23 Sep 2026 16:44:33 +0800 Subject: [PATCH 1/2] ci(governance): add CI workflow, gitignore target, and refine GitFlow branch policy --- .github/workflows/ci.yml | 88 ++++++++++++++++++++++ .gitignore | 2 + AGENTS.md | 14 +++- BRANCHING_STRATEGY.md | 154 +++++++++++++-------------------------- CONTRIBUTING.md | 22 +++--- 5 files changed, 165 insertions(+), 115 deletions(-) create mode 100644 .github/workflows/ci.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..88e2bc4 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,88 @@ +name: CI +on: + push: + branches: [dev, main] + pull_request: + branches: [dev, main] + +jobs: + backend-tests: + name: Backend Tests + runs-on: windows-latest + steps: + - uses: actions/checkout@v4 + + - name: Set up Python 3.12 + uses: actions/setup-python@v5 + with: + python-version: "3.12" + cache: "pip" + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + if (Test-Path backend/requirements.txt) { + pip install -r backend/requirements.txt + } + pip install pytest pytest-asyncio anyio httpx + + - name: Run pytest + run: | + cd backend + pytest -v + + frontend-build: + name: Frontend Build & Typecheck + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Install pnpm + uses: pnpm/action-setup@v3 + with: + version: 9 + + - name: Set up Node.js 20 + uses: actions/setup-node@v4 + with: + node-version: 20 + cache: "pnpm" + cache-dependency-path: frontend/pnpm-lock.yaml + + - name: Install dependencies + run: | + cd frontend + pnpm install --frozen-lockfile + + - name: Build frontend + run: | + cd frontend + pnpm build + + launcher-build: + name: Rust Launcher Build & Test + runs-on: windows-latest + steps: + - uses: actions/checkout@v4 + + - name: Check if launcher exists + id: check_launcher + shell: pwsh + run: | + if (Test-Path launcher/Cargo.toml) { + echo "exists=true" >> $env:GITHUB_OUTPUT + } else { + echo "exists=false" >> $env:GITHUB_OUTPUT + } + + - name: Set up Rust + if: steps.check_launcher.outputs.exists == 'true' + uses: actions-rust-lang/setup-rust-toolchain@v1 + + - name: Build and test launcher + if: steps.check_launcher.outputs.exists == 'true' + shell: pwsh + run: | + cd launcher + cargo build --release + cargo test diff --git a/.gitignore b/.gitignore index 6790810..49cdd98 100644 --- a/.gitignore +++ b/.gitignore @@ -13,6 +13,8 @@ dist/ dist-ssr/ build/ *.local +target/ +launcher/target/ # Python __pycache__/ diff --git a/AGENTS.md b/AGENTS.md index 781c3e9..89ab09e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,11 +1,15 @@ # AI Agent Guidelines & Coding Standards (AGENTS.md) -Welcome, AI Coding Agent (Antigravity, Claude Code, Cursor, GitHub Copilot, Devin, etc.). This document outlines the architectural invariants, operational rules, coding standards, and decision-making framework for working inside the **AI-Workflow** repository. +Welcome, AI Coding Agent (Antigravity, Claude Code, Cursor, GitHub Copilot, Devin, etc.). This document outlines the architectural invariants, operational rules, coding standards, and decision-making framework for working inside the **Berry AI Studio** repository. --- ## 1. Core Principles & Non-Negotiable Invariants +### Current Product Baseline + +Read `docs/PRODUCT_VISION.md`, `docs/PRD.md`, `docs/ARCHITECTURE.md`, and `docs/ROADMAP.md` before implementation. The primary canvas is a creative workspace with selection-based actions; users must not need to wire nodes to complete the image workflow. The five-type contract below applies to execution ports, not presentation objects. API-first preserves cloud-only operation while the first release also supports optional NVIDIA local engines. Do not treat historical prototype completion claims as product acceptance. + 1. **Simplicity Over Exposing Internal Complexity**: - ComfyUI's greatest pitfall is user overwhelm (spaghetti wires, latent/clip/vae micro-management). - Our UI must expose only **high-level, human-understandable nodes** (e.g., "Generate Image", "Expand Prompt", "Upscale Image", "Remove Background"). @@ -29,7 +33,7 @@ Welcome, AI Coding Agent (Antigravity, Claude Code, Cursor, GitHub Copilot, Devi ## 2. Codebase Organization ```text -AI-Workflow/ +AI-Studio/ ├── frontend/ # React 18+ / Vite / Tailwind / @xyflow/react │ ├── src/ │ │ ├── components/ @@ -108,6 +112,10 @@ async def execute_flux_node(inputs: dict, params: dict, context: ExecutionContex ## 4. Coding Conventions & Best Practices +### Project Language +- All project documentation, PR titles and descriptions, commit messages, issues, release notes, code comments, and other project-facing written artifacts must use English. +- Discussions may use the user's preferred language; record their outcomes in English in the repository. + ### Python (Backend) - **Runtime**: Python 3.10+ required. - **Async First**: Use `async`/`await` and `httpx.AsyncClient` for all I/O, API calls, and WebSockets. Never block the event loop with synchronous network or disk calls. @@ -124,7 +132,7 @@ async def execute_flux_node(inputs: dict, params: dict, context: ExecutionContex ## 5. Git & Branching Rules for Agents -- **Target Branch**: Never commit directly to `main`. When creating PRs or branches, branch off **`dev`** (`feature/` or `bugfix/`). +- **GitFlow**: Follow `BRANCHING_STRATEGY.md`. Feature, ordinary bug-fix, and documentation branches start from and target `dev`; release branches start from `dev` and target `main`, then synchronize back to `dev`; hotfix branches start from `main` and target `main`, then synchronize back to `dev`. Never commit directly to `main` or `dev`. - **Commit Messages**: Follow Conventional Commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`). - **Clean Commits**: Keep changes atomic. Do not bundle formatting refactors with behavioral feature additions. diff --git a/BRANCHING_STRATEGY.md b/BRANCHING_STRATEGY.md index d3499a4..28125a3 100644 --- a/BRANCHING_STRATEGY.md +++ b/BRANCHING_STRATEGY.md @@ -1,129 +1,77 @@ -# Git Branching Strategy & Release Specification +# Berry AI Studio GitFlow Branching and Release Policy -This document establishes the official Git branching model, branch governance, commit standards, and release workflows for the **AI-Workflow** repository. +Status: project policy. All branch names, commit messages, pull requests, tags, and release notes use English. ---- +## 1. Permanent Branches -## 1. Branch Architecture Overview +| Branch | Purpose | Rules | +| --- | --- | --- | +| `main` | Released, production-ready history | Protected. No direct commits or pushes. Release and hotfix PRs only. Every new release commit is tagged after merge and verification. | +| `dev` | Integration for the next release | Protected. Feature and ordinary bug-fix PRs merge here. A green `dev` build is integration evidence, not a release declaration. | -The repository follows a modified Git Flow model optimized for modern CI/CD, continuous development, and strict release stability. +Do not use `main` as a working branch. Do not tag a feature branch or `dev` as an official release. -``` -(main) v0.1.0 -------------------------------------> v0.2.0 (Release Tags) - ^ ^ - | | -(release) | [release/v0.2.0] - | ^ -(dev) +--- [PR Merge] <--- [PR Merge] <--- [PR Merge] (Integration) - ^ ^ - | | -(feature) [feature/canvas] [feature/api-runner] -``` +## 2. Short-Lived Branches -### The Primary Branches +| Pattern | Create from | Merge into | Purpose | +| --- | --- | --- | --- | +| `feature/` | `dev` | `dev` | New product capability or focused technical work. | +| `bugfix/` | `dev` | `dev` | Ordinary defects found during development. | +| `docs/` | `dev` | `dev` | Documentation-only changes. | +| `release/vX.Y.Z` | `dev` | `main`, then synchronize back to `dev` | Release stabilization, version numbers, changelog and packaging fixes. | +| `hotfix/vX.Y.Z` | `main` | `main`, then synchronize back to `dev` | Urgent correction to a released version. | -| Branch | Lifecycle | Protection Level | Purpose | -| :--- | :--- | :--- | :--- | -| **`main`** | Permanent | **Strictly Protected** | **Production / Official Releases**. Every commit on `main` represents a stable, release-ready artifact tagged with a Semantic Version (`vX.Y.Z`). Direct pushes are prohibited. | -| **`dev`** | Permanent | **Protected (Default Branch)** | **Active Integration**. All new features, performance improvements, and non-critical bug fixes converge here. Continuous Integration (CI) test suites run on every commit. | +Use lowercase, short, descriptive names. Include an issue ID when one exists. One branch should have a reviewable objective; avoid accumulating unrelated milestones in one branch. Existing historical branches are not renamed merely to satisfy this policy. ---- +## 3. Normal Development Flow -## 2. Supporting Branch Conventions +1. Update local `dev` from `origin/dev` and create a short-lived branch from it. +2. Implement a focused change with the relevant tests and English documentation. +3. Write English Conventional Commits, for example `feat(launcher): add startup readiness check` or `fix(runtime): preserve engine data during update`. +4. Open a PR targeting `dev`. Describe user-visible behavior, validation evidence, limitations and related requirement or issue IDs. +5. Keep the branch current with `dev` before merging. Resolve conflicts on the working branch and rerun affected checks. +6. Merge only after review and required checks pass. Prefer squash merge for feature, bug-fix and documentation PRs, yielding one clear change in `dev` per PR. Delete the temporary branch after merge. -All temporary branches must branch off the appropriate source and follow the standardized naming convention: +Never merge a feature branch directly into `main`. Never force-push a shared integration or release branch. Rebasing a personal branch before review is allowed; do not rewrite a shared branch after others depend on it. -``` -/ -``` +## 4. Release Flow -| Type | Source Branch | Target Branch | Description & Example | -| :--- | :--- | :--- | :--- | -| **`feature/*`** | `dev` | `dev` | New features, nodes, UI modules.
`feature/reactflow-canvas`
`feature/isolated-comfy-installer` | -| **`bugfix/*`** | `dev` | `dev` | Non-critical bug fixes during normal development.
`bugfix/dag-cycle-detection`
`bugfix/node-cache-hash` | -| **`release/*`** | `dev` | `main` & `dev` | Preparing a new production release (version bumping, changelog update, final freeze testing).
`release/v0.2.0` | -| **`hotfix/*`** | `main` | `main` & `dev` | Critical production security or runtime bug fixes requiring immediate deployment.
`hotfix/v0.1.1` | +1. Once the planned scope is integrated in `dev`, create `release/vX.Y.Z` from the current `dev` commit. No new features enter the release branch. +2. On the release branch, allow only regression fixes, version/changelog updates, packaging, security fixes and release documentation. Record the exact commit and test environment for the release candidate. +3. Run the complete release gate: required CI, Windows package installation and launcher checks, supported local/cloud creation journeys, update/recovery tests, and documented open limitations. Mock tests alone do not establish real engine or provider compatibility. +4. Open a PR from `release/vX.Y.Z` to `main`. Merge with a merge commit to preserve the release branch and the verified release candidate. Do not squash a release PR into unverified contents. +5. Verify the resulting `main` commit and create an annotated tag `vX.Y.Z` on that commit. Publish artifacts and release notes from the tagged commit only. Publishing is a separate release action. +6. Synchronize the released changes back into `dev` using a PR from `main` (or an equivalent reviewed back-merge that preserves the release commit). Resolve any conflicts and run affected checks. Then delete the release branch. ---- +If a release fix must also reach ongoing development before the final back-merge, apply it through a separate reviewed PR or wait for the back-merge. Do not silently cherry-pick the same change twice. -## 3. Commit Message Standards (Conventional Commits) +## 5. Hotfix Flow -All commits across all branches must follow the [Conventional Commits v1.0.0](https://www.conventionalcommits.org/) specification: +1. Create `hotfix/vX.Y.Z` from the current `main` release tag or commit, not from `dev`. +2. Make the smallest correction needed. Add a regression test when it verifies the failure. Update version and release notes. +3. Run targeted checks plus affected release smoke tests. Open a PR to `main` and merge with a merge commit after review. +4. Tag the merged `main` commit with the patch version and publish artifacts from that tag. +5. Back-merge `main` to `dev` through a reviewed PR. If a release branch is open, also synchronize the hotfix into that release branch and resolve conflicts before release. -``` -(): +## 6. Versioning and Tags -[optional body] +Use SemVer tags in the form `vMAJOR.MINOR.PATCH`. Increment major for incompatible public project/workflow formats or APIs, minor for compatible features, and patch for compatible fixes. Before a public 1.0 release, explain any compatibility breaks in release notes even when SemVer allows flexibility. -[optional footer(s)] -``` +The repository may contain historical commits without release tags. This policy governs future releases; do not create retrospective tags without matching verified artifacts and a documented reason. -### Allowed Types +## 7. Protection, Review and Checks -- **`feat`**: Introduces a new feature or user-facing capability. -- **`fix`**: Fixes a bug. -- **`docs`**: Documentation changes only. -- **`style`**: Formatting, missing semi-colons, whitespace (no code change). -- **`refactor`**: Code restructuring that neither fixes a bug nor adds a feature. -- **`perf`**: Performance improvement. -- **`test`**: Adding missing tests or correcting existing tests. -- **`build`**: Changes that affect the build system or external dependencies (npm, uv, pyproject, vite). -- **`ci`**: Changes to CI/CD configuration files and scripts (GitHub Actions). -- **`chore`**: Maintenance tasks, housekeeping, tooling updates. +Configure repository branch protection for `main` and `dev`: no direct pushes, required status checks, and up-to-date PR branches. -### Examples +- **Merging into `dev`**: Feature, bug-fix, and documentation pull requests targeting `dev` may be self-merged once all required automated checks pass and the PR checklist is fulfilled. Failing checks must never be bypassed. +- **Promotion to `main`**: Release (`release/vX.Y.Z`) and hotfix (`hotfix/vX.Y.Z`) pull requests targeting `main` strictly require product-owner release approval and verified release evidence before publication. -- `feat(canvas): add single-node run button and isolated execution trigger` -- `fix(engine): resolve race condition in dag topological sort when nodes fail` -- `docs(readme): add quickstart guide for isolated comfyui runtime` -- `refactor(runners): unify openai-compatible request payload adapter` +At minimum, gate changes with the checks that exist and are relevant: backend tests, frontend type-check/build, Rust launcher build/tests, formatting/lint where configured, and a documentation/link check. Add CI workflows for these gates if missing. Real Windows packaging, local engines, cloud providers and hardware need recorded manual/integration evidence at release time; mark unavailable checks unverified rather than passed. ---- +Never commit secrets, model weights, generated assets, local runtime directories, or build outputs unless a reviewed packaging requirement explicitly calls for a generated artifact. Keep application and engine update changes separate where possible. -## 4. Pull Request (PR) Lifecycle & Merge Rules +## 8. Current Large Feature Branch -### Branch Protection Rules -1. **No direct pushes** to `main` or `dev`. -2. **Review Requirements**: At least 1 code review approval required before merge. -3. **CI Status Checks**: All automated tests, type checks (`tsc`, `pyright`/`mypy`), and linter runs (`eslint`, `ruff`) must pass. -4. **Up-to-Date**: Branches must be rebased or updated with target before merging. +`feature/berry-product-alignment` currently holds reported M0–M6 implementation. Treat its completion reports as developer evidence awaiting unified acceptance. Do not merge it into `main` or tag a release directly. -### Merge Strategies -- **Merging into `dev`**: **Squash and Merge** or **Rebase and Merge** (keeps the integration history linear and readable). -- **Merging into `main`**: **Merge Commit** (preserves the release branch history and tag pointers) or **Squash and Merge** for hotfixes. - ---- - -## 5. Release Workflow & Semantic Versioning - -This project adheres to **Semantic Versioning (SemVer 2.0.0)**: -`MAJOR.MINOR.PATCH` - -- **MAJOR**: Incompatible API or workflow graph schema breaking changes. -- **MINOR**: Backward-compatible new functionality (e.g., new node types, runner drivers). -- **PATCH**: Backward-compatible bug fixes and security patches. - -### Step-by-Step Release Procedure - -1. **Cut Release Branch**: - ```bash - git checkout dev - git pull origin dev - git checkout -b release/v0.2.0 - ``` -2. **Stabilization & Bumping**: - - Bump version numbers in `package.json`, `pyproject.toml`, etc. - - Update `CHANGELOG.md` with notes from the milestone. - - Run full regression tests and verification suites. -3. **Merge Release into `main`**: - - Create PR from `release/v0.2.0` into `main`. - - Once approved and merged, tag the release: - ```bash - git checkout main - git pull origin main - git tag -a v0.2.0 -m "Release v0.2.0: Isolated ComfyUI engine integration" - git push origin v0.2.0 - ``` -4. **Back-merge into `dev`**: - - Merge `release/v0.2.0` back into `dev` to ensure version bumps and changelog persist. - - Delete `release/v0.2.0`. +Before integrating it into `dev`, prepare a PR with a change summary by requirement, current test/build results, known limitations, and a separate list of real Windows, local-engine and cloud scenarios that remain unverified. Review the diff for unrelated changes and split follow-up work into focused branches where practical. If the branch cannot be split safely after shared commits, integrate it as one reviewed exception and return to small branches afterward. Unified product acceptance and release promotion remain separate decisions. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ff6f71a..07e2383 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ -# Contributing to AI-Workflow +# Contributing to Berry AI Studio -First off, thank you for considering contributing to **AI-Workflow**! Open-source thrives because of community members like you. +First off, thank you for considering contributing to **Berry AI Studio**! Open-source thrives because of community members like you. This document outlines the workflow and quality guidelines for contributing code, documentation, and workflow presets. @@ -14,9 +14,11 @@ All contributors and participants are expected to adhere to our [Code of Conduct ## Branching & Release Model -We strictly follow a structured Git branching strategy: -- **`main`**: The official, production-ready release branch. Direct commits are forbidden. -- **`dev`**: The active integration branch. **All feature and bug fix pull requests must target `dev`**. +We follow [GitFlow](BRANCHING_STRATEGY.md): +- **`main`**: Protected, tagged release history. Direct commits are forbidden. +- **`dev`**: Protected integration branch. Feature, ordinary bug-fix, and documentation pull requests target `dev`. +- **`release/vX.Y.Z`**: Created from `dev` and merged into `main`, then synchronized back to `dev`. +- **`hotfix/vX.Y.Z`**: Created from `main` and merged into `main`, then synchronized back to `dev`. Before opening a PR, please read our complete [Branching Strategy Specification](BRANCHING_STRATEGY.md). @@ -34,8 +36,8 @@ Before opening a PR, please read our complete [Branching Strategy Specification] ### 1. Clone the Repository ```bash -git clone https://github.com/BerryUIKI/AI-Workflow.git -cd AI-Workflow +git clone https://github.com/BerryUIKI/AI-Studio.git +cd AI-Studio git checkout dev ``` @@ -68,6 +70,8 @@ The backend API and WebSocket server will be available at `http://localhost:8000 ## Contribution Workflow +Use English for all project documentation, PR titles and descriptions, commit messages, issues, release notes, code comments, and other project-facing written artifacts. + 1. **Check Issues**: Check existing GitHub Issues or start a discussion before making substantial architectural changes. 2. **Branch from `dev`**: ```bash @@ -85,7 +89,7 @@ The backend API and WebSocket server will be available at `http://localhost:8000 - Frontend: `pnpm typecheck && pnpm lint` - Backend: `pytest` and `ruff check .` 6. **Open a Pull Request**: - - Base branch: **`dev`**. + - Base branch: **`dev`** for features, ordinary fixes, and documentation; follow the release and hotfix routes in the branching policy for those branch types. - Fill out the PR template completely. - Link related issue numbers (e.g., `Fixes #42`). @@ -105,7 +109,7 @@ When contributing new nodes or canvas components, please keep our core tenets in ## Pull Request Checklist Before submitting your PR, ensure: -- [ ] PR targets the **`dev`** branch. +- [ ] PR targets the branch required by its GitFlow branch type. - [ ] All new and existing tests pass. - [ ] Code adheres to TypeScript and Python formatting guidelines. - [ ] User-facing features include updated documentation or tooltips. From 44160fbd1972da0a8fcc5c0938ab852a50f797e6 Mon Sep 17 00:00:00 2001 From: Berry Wahlberg <40695099+BerryUIKI@users.noreply.github.com> Date: Wed, 23 Sep 2026 16:46:20 +0800 Subject: [PATCH 2/2] fix(frontend): add packages array to pnpm-workspace.yaml for CI --- frontend/pnpm-workspace.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/frontend/pnpm-workspace.yaml b/frontend/pnpm-workspace.yaml index 5ed0b5a..7f5dfdd 100644 --- a/frontend/pnpm-workspace.yaml +++ b/frontend/pnpm-workspace.yaml @@ -1,2 +1,5 @@ +packages: + - '.' + allowBuilds: esbuild: true