Contributing

한국어로 보기

Contributing

Small documentation fixes are welcome directly. For behavior or design changes, open an issue first so the trade-off can be discussed before implementation. Korean is first-class for issues and pull requests; English is welcome too.

The repository's CONTRIBUTING.md is the canonical contribution guide. Follow any repository-local instructions in AGENTS.md as well.

Set up and verify locally

Contributors need Node.js 20 or later, pnpm 9, and Docker for local Postgres. The standard flow is:

pnpm install
cp .env.example .env
pnpm db:up
pnpm migrate && pnpm seed
pnpm dev

Before opening a pull request, run:

pnpm typecheck
pnpm test

For a Rust shim change, also run cargo clippy --all-targets -- -D warnings from shim/rust. Do not claim checks that you did not run.

Respect the contracts

The data model and collection contract need extra care. A change to UsageEvent must update both packages/core and the Rust shim, and changes to the data model or collection contract require the relevant architecture decision record to stay accurate. Start with Architecture before changing these boundaries.

Keep secrets out of examples, fixtures, commits, and PR descriptions. Security vulnerabilities must use the private reporting process, not an issue or pull request.

Commit and pull-request expectations

• Use Conventional Commits: <type>(<scope>): <subject>, with no period at the end of the subject.
• Use the allowed types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, or revert.
• Complete the pull-request template sections: 목적, 내용(의도 포함), and 성공기준. List only checks actually performed under the success criteria.

Documentation and Wiki boundary

The repository documentation is the canonical source for exact deployment settings, architecture contracts, and security policy. The Wiki is a navigational, task-oriented companion. Update the matching English and Korean Wiki pages when a change affects user actions, operational decisions, or a security boundary; link to the repository document rather than duplicating volatile configuration details.

For a Wiki-only wording or navigation improvement, keep the change scoped to the Wiki repository. For a changed command, API behavior, environment variable, or design contract, update the canonical repository document in the same change or link to the issue that tracks it.