# Contributing Guide

> **Chinese version**: [CONTRIBUTING.zh.md](CONTRIBUTING.zh.md)

## Prerequisites

See [docs/contributing/development.md](docs/contributing/development.md) for environment setup. You will need:

- Node.js 22+
- [bun](https://bun.sh)
- [Rust stable + Cargo](https://rustup.rs) for the local AionCore backend
- [prek](https://github.com/j178/prek) (`npm install -g @j178/prek`)

## Rule 1: Atomic PRs

Each pull request must contain **exactly one feature or one bug fix** that cannot be further decomposed.

**How to check:** Ask yourself (or an AI): _"Can this diff be split into multiple independently mergeable PRs?"_ If yes, split it before submitting.

### Examples

**Acceptable (single PR):**

- A bug fix with one root cause, even if it touches multiple files (e.g., fixing toast z-index across modal and chat layers)
- A single coherent feature (e.g., team creation modal with form validation)

**Must be split into separate PRs:**

- Team chat scroll fix + Sentry user tracking + office preview performance optimization = 3 PRs
- Unrelated bug fixes bundled together (e.g., titlebar navigation fix + i18n missing key + speech input UI fix)
- Independent technical layers (e.g., IPC bridge refactor + renderer component + worker process change for unrelated features)

## Rule 2: Commit and PR Title Format

Commit messages and PR titles must use Conventional Commit format in English:

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

Use one of these types:

| Type       | Meaning                  | Changelog visibility |
| ---------- | ------------------------ | -------------------- |
| `feat`     | New user-facing behavior | Visible              |
| `fix`      | Bug fix                  | Visible              |
| `perf`     | Performance improvement  | Visible              |
| `refactor` | Code restructuring       | Visible              |
| `docs`     | Documentation            | Visible              |
| `style`    | Formatting or styles     | Hidden               |
| `chore`    | Maintenance work         | Hidden               |
| `test`     | Tests                    | Hidden               |
| `ci`       | CI configuration         | Hidden               |
| `build`    | Build system             | Hidden               |

Examples:

- `fix(preview): restore local html loading`
- `feat(workspace): add file preview shortcuts`
- `docs(contributing): document pr title format`

## Rule 3: Pass Local Checks Before Push

CI will reject your PR if these checks fail. Run them locally **before pushing** to save time.

### Step-by-step

```bash
# 1. Format (always run — covers .ts, .tsx, .css, .json, .md)
bun run format

# 2. Lint (skip if no .ts/.tsx files changed)
bun run lint

# 3. Type check (skip if no .ts/.tsx files changed)
bunx tsc --noEmit

# 4. i18n validation (only if you changed files in src/renderer/, locales/, or src/common/config/i18n/)
bun run i18n:types
node scripts/check-i18n.js

# 5. Tests
bunx vitest run
```

### One-command alternative

This replicates the exact CI quality check, then runs tests:

```bash
prek run --from-ref origin/main --to-ref HEAD
bunx vitest run
```

> `prek` runs format-check + lint + tsc in read-only mode. If it reports issues, run the auto-fix commands above first, then re-run prek.

### Common failures and fixes

| Failure       | Fix                                                                  |
| ------------- | -------------------------------------------------------------------- |
| Format errors | `bun run format` (auto-fixes)                                        |
| Lint errors   | `bun run lint:fix` for auto-fixable issues; fix the rest manually    |
| Type errors   | Fix the TypeScript issue, then re-run `bunx tsc --noEmit`            |
| i18n errors   | Check for missing keys; run `bun run i18n:types` to regenerate types |
| Test failures | Fix the failing test or implementation; re-run `bunx vitest run`     |

## Enforcement

When these rules are not followed, maintainers may:

1. **Close and request resubmission** (preferred) — you retain full credit upon proper resubmission.
2. **Cherry-pick valuable portions** — your authorship is preserved in git history, but the original PR shows as "Closed" rather than "Merged".

Code style, dependency choices, and documentation polish are handled by maintainers post-merge. Focus your PR on the functional change.