Thank you for your interest in contributing to Tutti! This guide covers everything you need to set up a development environment, follow our conventions, and get your changes merged.

By participating in this project, you agree to follow our Code of Conduct.

Note: this codebase uses the internal codename tutti — you will see it in directory and binary names such as services/tuttid.

Repository Layout

apps/desktop: Electron desktop shell, renderer UI, preload bridge, and native desktop integration
services/tuttid: long-running local daemon and primary business core
packages/clients/*: shared domain-specific clients
packages/configs/*: shared engineering config
packages/ui/*: shared visual system boundaries

Development Environment

Recommended local prerequisites:

Node.js 24 or newer; .node-version pins the project baseline
pnpm 10.11.0
Go 1.24
golangci-lint v2.12.0

Install workspace dependencies:

pnpm install

For a new linked Git worktree, use this instead:

pnpm setup:worktree

It installs workspace dependencies, then prewarms Electron before parallel tests run. The command reuses the shared Electron download cache and extracts the runtime into the new worktree; it never reuses another worktree's Electron.app.

Install the pinned golangci-lint version:

pnpm install:golangci-lint

Check local prerequisites:

pnpm setup:dev

Start the desktop app in development with prerequisite checks and a prebuilt tuttid:

make dev-gui

If you already have a warmed daemon binary and only want the raw Electron/Vite loop, pnpm dev:desktop still works.

Common Commands

make dev-gui
pnpm build
pnpm typecheck
pnpm lint
pnpm lint:ts
pnpm lint:go
pnpm test:ts
pnpm test:go
pnpm check:golangci-version
pnpm install:golangci-lint
pnpm generate:defaults
pnpm check:defaults-generated

Full validation entrypoint:

pnpm check:full

Repository Rules

Business logic belongs in services/tuttid
UI and desktop integration belong in apps/desktop
Code should move into packages/ only when there is a real shared boundary
Business-code files should stay at or below 800 lines; crossing the limit is a refactoring signal

Deeper references:

Architecture overview: docs/architecture/README.md
Project structure: docs/architecture/project-structure.md
Repository conventions: docs/conventions/README.md
Static analysis and lint rules: docs/conventions/static-analysis.md
Agent contributor instructions: AGENTS.md

Commit Conventions

We follow Conventional Commits:

<type>(<scope>): <subject>

Examples from this repository:

fix(workspace-files): avoid protected directory prefetch
fix(agent): preserve provider permission defaults

Common types: feat, fix, docs, refactor, test, chore.

Developer Certificate of Origin (DCO)

We require contributors to certify the Developer Certificate of Origin. It is a lightweight statement that you have the right to submit your contribution under the project's license (Apache-2.0).

Sign off each commit with the -s flag:

git commit -s -m "feat(scope): add something"

This appends a Signed-off-by: Your Name <your@email> line to the commit message.

Pull Request Workflow

Fork the repository and create a branch from main. Suggested branch naming: feat/..., fix/..., docs/...
Make your changes; keep each PR focused on a single concern
Open a PR with a clear description of the motivation and changes
CI classifies the changed files and runs the relevant TypeScript, Go, package, and tooling checks; all selected checks must pass
A maintainer reviews your PR; please respond to feedback and keep the conversation in the PR

Local hooks use husky:

pre-commit runs staged formatting and UI-boundary checks
pre-push runs changed-aware push validation with pnpm check:changed -- --push-ready

Pull Request Review Gate

Tutti uses the external-pr-review-gate workflow to separate internal team changes from external contributions. Internal authors are defined by the organization variable TUTTI_RD_MEMBERS; the tutti-rd GitHub team is the review target for external PRs.

PRs opened by tutti-rd members do not automatically request reviewers and can pass the review gate without a separate official approval
PRs opened by non-tutti-rd authors automatically request review from @tutti-os/tutti-rd
External PRs can merge only after a tutti-rd member approves the current head commit
Pushing a new commit refreshes the gate; the new head commit needs a fresh passing review
Maintainers must update both TUTTI_RD_MEMBERS and the tutti-rd team when official team membership changes

---
config:
  layout: dagre
  theme: redux
  look: neo
---
flowchart TB
    A["PR opened / reopened / marked ready for review / new commit pushed"] --> B{"Is the PR author in the official member list?"}
    B -- Yes --> C["Do not automatically request reviewers"]
    C --> P["✅ Passed"]
    P --> M["Can merge"]
    B -- No --> D["Automatically request @tutti-os/tutti-rd review"]
    D --> E{"Does the current head commit have an official review?"}
    E -- Approved --> P
    E -- No passing review --> F["❌ Failed"]
    F --> N["Cannot merge"]
    G["External contributor pushes a new commit"] --> A

    G@{ shape: rounded}

Documentation Language Policy

README.* and CONTRIBUTING.* are maintained in English, Simplified Chinese, and Traditional Chinese
English is the source of truth — when you change README.md or CONTRIBUTING.md, update *.zh-CN.md and *.zh-TW.md in the same PR
If a translation conflicts with the English version, the English version prevails
LICENSE, NOTICE, CODE_OF_CONDUCT.md, SECURITY.md, and the docs/ tree are English-only

Reporting Issues

Bug reports and feature requests: use the issue templates
Security vulnerabilities: do not open a public issue — see SECURITY.md

License

By contributing to Tutti, you agree that your contributions will be licensed under the Apache License 2.0.

6.5 KiB Raw Permalink Blame History

Contributing to Tutti