贡献 Maka

English

缺陷和具体提案使用 Issues，一般问题使用 Discussions，安全漏洞通过 SECURITY.md报告。认领未分配 issue 时，评论内容只写 take；放弃认领只写 untake。

项目方向、治理和重要产品决策在 dev@maka.apache.org讨论。实现细节可以在 PR 中讨论。

开发

安装 Rust stable、Node.js 24 LTS、npm 11.19.0、just、cargo-nextest 和 Python 3。许可证检查还需 cargo-deny。Windows 需要将 Git for Windows 的 sh 加入 PATH。

just setup
just run --help
just check

just check 执行格式、lint、类型、测试和许可证检查。针对 Rust 局部修改，可运行 cargo nextest run -p CRATE；通过 --lib 或 --test NAME 限制构建的测试目标。先运行与改动行为相关的检查，再做完整仓库检查。

产品指南说明 TypeScript 开发方式，插件指南介绍声明与组合。原生打包和 V8 要求见 scripts/rust。官网使用独立的 manifest 和锁文件。

代码与文档

  • 使用 name.rs 和同名 name/ 目录组织子模块。单元测试与实现放在一起，集成测试位于 tests/。
  • 测试可观察行为和重要失败边界，避免重复夹具、源码文本断言和固定延时。
  • 领域策略留在插件，Host 管理准入和资源结算，服务接收显式能力。
  • 用类型表达闭合状态，通过 schemars 生成 schema。数据库变更使用 SQLx migration。
  • 协议字段与本地化文案分离，保留完整的 en、zh-CN 和 zh-TW locale。
  • 维护简洁的中英文 README，说明职责和有用入口；字段级细节链接到 schema。

提交与评审

标题使用 Conventional Commits，分支使用 <type>/<description>。填写 PR 模板，说明结果及相关验证；UI 变更附截图或录屏。仓库使用 squash merge，PR 标题会成为最终提交标题。

每份贡献都需要一位人类负责人，对准确性、来源和许可负责。只提交有权贡献的内容，遵循 Apache-2.0，保留第三方归属信息。参阅来源记录和文件头规范。

在 PR 中披露实质性的生成工具使用并注明工具名称。翻译、措辞修改、自动补全和拼写修正不计入此范围。包含实质性 AI 编写内容的提交应携带 Generated-by: <tool>，并在 squash 或 amend 后保留。自动消息应表明身份。

Agent 可以提交和推送。合并到 main 需要另一位 committer 批准，并通过 test 检查。AI 评审不能替代独立的人类判断。后续推送不会自动撤销已有批准；变更超出原评审范围时，应再次请求评审。维护者决定评审是否充分。