Contributing to Maka

简体中文

Use issues for bugs and concrete proposals, and Discussions for questions. Report vulnerabilities through SECURITY.md. Comment exactly take to claim an unassigned issue, or untake to release it.

Discuss project direction, governance and material product decisions on dev@maka.apache.org. Implementation details can be discussed in the pull request.

Develop

Install Rust stable, Node.js 24 LTS, npm 11.19.0, just, cargo-nextest and Python 3. License checks also use cargo-deny. On Windows, put Git for Windows' sh on PATH.

just setup
just run --help
just check

just check runs formatting, lint, type checks, tests and license checks. For a focused Rust change, use cargo nextest run -p CRATE; --lib or --test NAME limits which test targets are built. Run the checks relevant to the changed behavior before the full repository check.

The product guide explains TypeScript development. The plugin guide covers declarations and composition. Native packaging and V8 requirements live in scripts/rust. The website has a separate manifest and lockfile.

Code and documentation

  • Use name.rs with name/ for child modules. Keep unit tests with their implementation and integration tests under tests/.
  • Test observable behavior and meaningful failure boundaries. Avoid duplicate fixtures, source-text assertions and fixed sleeps.
  • Keep domain policy in plugins. Host owns admission and resource settlement; services receive explicit capabilities.
  • Model closed states with types and generate schemas with schemars. Put database changes in SQLx migrations.
  • Keep protocol fields separate from localized copy. Preserve full en, zh-CN and zh-TW locale tags.
  • Maintain concise English and Chinese README counterparts. Explain responsibilities and useful entrypoints; link to schemas for field-level detail.

Submit and review

Use Conventional Commit titles and <type>/<description> branches. Fill in the pull request template, describe the result and relevant verification, and include screenshots or a recording for UI changes. Squash merging makes the PR title the final commit title.

Each contribution has a human owner responsible for its accuracy, provenance and licensing. Submit only work you have the right to contribute, under Apache-2.0, and preserve third-party attribution. See the source records and header policy.

Disclose substantive generative-tool use in the PR and name the tool. Translation, wording edits, autocomplete and spelling correction do not count. Material AI-authored commits carry Generated-by: <tool>, preserved through squash or amend. Automated messages identify themselves.

Agents may commit and push. Merging to main requires approval from another committer and a passing test check. AI review does not replace independent human judgment. Approval remains valid after later pushes; ask for another look when the change grows beyond what was reviewed. A maintainer decides whether the review is sufficient.