Clawith/CONTRIBUTING.md

# Contributing to Clawith 🦞

Thanks for your interest in contributing! Whether it's a bug fix, new feature, translation, or documentation improvement — every contribution matters.

## Quick Start

1. **Fork** this repo and clone your fork
2. Set up the dev environment:
   ```bash
   bash setup.sh    # Backend + frontend + database
   bash restart.sh  # Start services → http://localhost:3008
   ```
3. Create a branch: `git checkout -b my-feature`
4. Make your changes
5. Push and open a Pull Request

## What Can I Contribute?

| Area | Examples |
|------|---------|
| 🐛 Bug fixes | UI glitches, API errors, edge cases |
| ✨ Features | New agent skills, tools, UI improvements |
| 🔧 MCP Integrations | New MCP server connectors |
| 🌍 Translations | New languages or improving existing ones |
| 📖 Documentation | README, guides, code comments |
| 🧪 Tests | Unit tests, integration tests |

**New to the project?** Look for issues labeled [`good first issue`](https://github.com/dataelement/Clawith/labels/good%20first%20issue).

## Bug Reports

When reporting a bug, please include:
- Steps to reproduce
- Expected vs actual behavior
- Clawith version and deployment method (Docker / Source)
- Logs or screenshots if available

**Priority guide:**

| Type | Priority |
|------|----------|
| Core functions broken (login, agents, security) | 🔴 Critical |
| Non-critical bugs, performance issues | 🟡 Medium |
| Typos, minor UI issues | 🟢 Low |

## Feature Requests

Please describe:
- The problem you're trying to solve
- Your proposed solution (if any)
- Why this would be useful

## Pull Request Process

1. **Link an issue** — Create one first if it doesn't exist
2. **Keep it focused** — One PR per feature/fix
3. **Test your changes** — Make sure nothing is broken
4. **Follow code style:**
   - Backend: Python — formatted with `ruff`
   - Frontend: TypeScript — standard React conventions
5. Use `Fixes #<issue_number>` in the PR description

## Working on Multiple Features

It is common to develop several improvements in one sitting before submitting. Rather than sending one giant PR, please split your work into smaller, focused PRs — this makes review faster and merges cleaner.

### Preferred: one branch per feature from the start

```bash
# Start each new feature from a fresh branch off main
git checkout main && git pull
git checkout -b feat/i18n-emoji-cleanup

# ... develop, commit ...

git checkout main
git checkout -b feat/admin-email-templates

# ... develop, commit ...
```

Each branch becomes one PR. Small, clean, easy to review.

### Already mixed everything into one branch? Split it with `git add -p`

`git add -p` (patch mode) lets you selectively stage individual change *hunks* from a file — perfect for creating several commits from one messy branch.

**Step-by-step example:**

```bash
# Assume your branch is called my-big-branch and has 3 logical changes mixed in.
# Goal: create 3 separate PRs from it.

# --- PR 1: emoji cleanup ---
git checkout -b feat/i18n-emoji-cleanup main

# Interactively stage only the emoji-related hunks from en.json and zh.json:
git add -p frontend/src/i18n/en.json   # answer y/n for each hunk
git add -p frontend/src/i18n/zh.json
git commit -m "fix: remove emoji from i18n strings"
git push -u origin feat/i18n-emoji-cleanup
# → open PR

# --- PR 2: hardcoded strings → t() ---
git checkout -b feat/i18n-component-strings main

git add -p frontend/src/pages/AgentDetail.tsx   # stage only t() hunk
git add -p frontend/src/components/ChannelConfig.tsx
git commit -m "feat: replace hardcoded UI strings with i18n t() calls"
git push -u origin feat/i18n-component-strings
# → open PR

# --- PR 3: admin improvements ---
git checkout -b feat/admin-improvements main
git checkout my-big-branch -- frontend/src/pages/AdminCompanies.tsx  # cherry-pick whole file if clean
git commit -m "feat: improve admin company settings"
git push -u origin feat/admin-improvements
# → open PR
```

**Key commands:**

| Command | What it does |
|---------|-------------|
| `git add -p <file>` | Stage hunks interactively (y = yes, n = no, s = split hunk smaller) |
| `git checkout <branch> -- <file>` | Copy a whole file from another branch |
| `git cherry-pick <commit>` | Apply a single commit to the current branch |
| `git diff main...HEAD -- <file>` | Preview what changed in a specific file vs main |

### Tips

- **Commit early, commit often** on your dev branch — individual commits are much easier to cherry-pick later than one large commit.
- Use descriptive commit messages (e.g. `fix: remove emoji from zh.json`, not `update stuff`).
- If two features touch the same file heavily, submit PR 1 first, wait for it to merge, then rebase PR 2 on `main` before opening it.


## Project Structure

```
backend/
├── app/
│   ├── api/          # FastAPI route handlers
│   ├── models/       # SQLAlchemy models
│   ├── services/     # Business logic
│   └── core/         # Auth, events, middleware
frontend/
├── src/
│   ├── pages/        # Page components
│   ├── components/   # Reusable UI components
│   ├── stores/       # Zustand state management
│   └── i18n/         # Translations
```

## Language Policy

To ensure all contributors can participate effectively, please use **English** for issues, PRs, and code comments.

为了确保所有贡献者都能有效参与，请使用**英语**提交 Issue、PR 和代码注释。

すべてのコントリビューターが効果的に参加できるよう、Issue、PR、コードコメントは**英語**でお願いします。

모든 기여자가 효과적으로 참여할 수 있도록, Issue, PR, 코드 코멘트는 **영어**로 작성해 주세요.

Para garantizar que todos los contribuidores puedan participar de manera efectiva, utilice **inglés** para issues, PRs y comentarios de código.

لضمان مشاركة جميع المساهمين بفعالية، يرجى استخدام **اللغة الإنجليزية** في الـ Issues وطلبات السحب وتعليقات الكود.

## Windows Development

Clawith is primarily developed on Linux/macOS, but can run on Windows with a few adjustments.

### Prerequisites

- **Python 3.11+** — Install from [python.org](https://www.python.org/downloads/) (check "Add to PATH")
- **Node.js 18+** — Install from [nodejs.org](https://nodejs.org/)
- **Docker Desktop** — For PostgreSQL and Redis (recommended over native installs)

### Database & Redis via Docker

```powershell
docker run -d --name clawith-postgres -p 5432:5432 -e POSTGRES_PASSWORD=yourpass -e POSTGRES_DB=clawith postgres:15
docker run -d --name clawith-redis -p 6379:6379 redis:7
```

### Backend Setup

```powershell
cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

# Create .env (copy from .env.example and adjust DATABASE_URL / REDIS_URL)
# Run database migrations
alembic upgrade head

# Start the server
uvicorn app.main:app --host 0.0.0.0 --port 8000
```

### Frontend Setup

```powershell
cd frontend
npm install
npm run dev
```

### Common Windows Issues

| Issue | Solution |
|-------|----------|
| `UnicodeEncodeError` / GBK encoding | Set `PYTHONUTF8=1` in environment variables, or run `chcp 65001` before starting |
| System proxy intercepting LLM API calls | Set `NO_PROXY=*` or unset `HTTP_PROXY` / `HTTPS_PROXY` in your terminal |
| `uvicorn --reload` crashes with watchfiles | Remove `--reload` flag, or install `watchfiles`: `pip install watchfiles` |
| File path errors with backslashes | Use `pathlib.Path` — the codebase already does this in most places |

> **Note**: The recommended deployment method is Docker (`docker compose up -d`), which works identically on Windows, macOS, and Linux. The instructions above are for local development without Docker.

## Getting Help

Stuck? Open a [Discussion](https://github.com/dataelement/Clawith/discussions) or ask in the related issue. We're happy to help! 🙌