Commit style

#Conventional commits

Format:

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

[optional body]
[optional footer: closes #nnn]

Types: feat, fix, docs, refactor, test, chore, perf, ci, style, arch, build, merge, quality, release, reliability, and security. Scope: package or area — core, react, adapters, docs, ci, etc.

Examples:

feat(adapters): add Mistral adapter with streaming
fix(react): useChat stop() races with in-flight token
docs(recipes): add cost-guarded chat
refactor(core): split controller events into sub-emitter
test(ink): cover keyboard navigation across message list

Subject ≤ 72 chars, imperative mood ("add", not "added"). Body wraps at 100.

#Enforcement

Commit-message discipline is enforced locally and in pull-request CI. Invalid messages fail before a push, and the same range is checked again on GitHub.

#Repository setup

• @commitlint/cli + @commitlint/config-conventional — validates the message
• .husky/commit-msg — blocks invalid commits locally
• Commitlint CI job — checks every commit in the pull request range

#What a complete PR looks like

1. The repository ships commitlint.config.cjs:

   module.exports = { extends: ['@commitlint/config-conventional'] }

2. The dependencies are pinned in the workspace root package.json:

   "@commitlint/cli": "21.2.1",
   "@commitlint/config-conventional": "21.2.0",
   "husky": "^9.0.0"

3. Husky runs this commit-msg hook automatically after pnpm install:

   echo 'pnpm exec commitlint --edit "$1"' > .husky/commit-msg

4. CI runs the commit range check:

   - run: pnpm exec commitlint --from="${{ github.event.pull_request.base.sha }}" --to="${{ github.event.pull_request.head.sha }}" --verbose

To validate the contract locally without creating a commit, run:

pnpm test:commitlint

If a hook blocks a message, fix the subject or amend the commit before pushing.

#Changesets (for publishable packages)

If your PR changes a package that ships to npm, add a changeset:

pnpm changeset

Walk through the prompts. This generates a markdown file describing the change and its semver bump. Commit it.

#PR checklist

Before marking a PR ready for review:

• pnpm lint passes
• pnpm test passes
• New/changed behavior has a test
• Public API changes have a docstring + doc example
• Changeset added (if a published package changed)
• Commit messages pass pnpm exec commitlint
• PR description explains why, not just what

#Review cadence

• Draft PRs are fine — open early to show direction.
• Maintainers triage within 2 business days.
• Expect 1–3 review rounds. Be kind, we will too.