Contributing Guide

Chinese version: CONTRIBUTING.zh.md

Prerequisites

See docs/contributing/development.md for environment setup. You will need:

Node.js 22+
bun
Rust stable + Cargo for the local AionCore backend
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:

<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

# 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:

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:

Close and request resubmission (preferred) — you retain full credit upon proper resubmission.
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.

4.3 KiB Raw Blame History