Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
118 lines (85 loc) · 4 KB

CONTRIBUTING.md

File metadata and controls

118 lines (85 loc) · 4 KB
Raw

Contributing to Berry AI Studio

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.

Code of Conduct

All contributors and participants are expected to adhere to our Code of Conduct. Please report any unacceptable behavior to the project maintainers.

Branching & Release Model

We follow GitFlow:

  • 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.

Development Environment Setup

Prerequisites

  • Node.js: v18.0.0+ (or v20.x LTS recommended)
  • pnpm: v8.x or v9.x (corepack enable or npm install -g pnpm)
  • Python: 3.10+ or 3.12+
  • uv (recommended) or standard venv

1. Clone the Repository

git clone https://github.com/BerryUIKI/AI-Studio.git
cd AI-Studio
git checkout dev

2. Setup the Frontend

cd frontend
pnpm install
pnpm dev

The frontend canvas will be available at http://localhost:5173.

3. Setup the Backend

cd ../backend
python -m venv .venv

# On Windows pwsh:
.venv\Scripts\Activate.ps1
# On Linux/macOS:
source .venv/bin/activate

pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

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: 
    git checkout dev
git pull origin dev
git checkout -b feature/my-awesome-feature
  3. Make Atomic Changes:
    • Write clean, self-documenting code.
    • Maintain unit tests for new logic.
  4. Commit with Conventional Commits:
    • Follow the standard format: type(scope): description.
    • Example: feat(nodes): add ElevenLabs TTS voice synthesis node
  5. Run Checks Locally:
    • Frontend: pnpm typecheck && pnpm lint
    • Backend: pytest and ruff check .
  6. Open a Pull Request:
    • 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).

Design Philosophy

When contributing new nodes or canvas components, please keep our core tenets in mind:

  • Keep It Simple: Never expose raw low-level tensor pipelines or complex mathematical node parameters on the main canvas.
  • Universal Types: All node connections must utilize the 5 core types (string, image, audio, video, json).
  • Cost Awareness: Respect user API tokens. Ensure nodes support dirty-checking and state caching.
  • System Isolation: Any feature interacting with local ComfyUI must never pollute the host system's global environment.

Pull Request Checklist

Before submitting your PR, ensure:

  • 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.
  • Commit history is clean and uses conventional commit messages.

Thank you for helping make AI creation accessible and enjoyable for everyone!