贡献指南

本指南汇集了参与 luna-poly 开发的约定。Luna Flow 组织规则在此之上同样适用。

提交拉取请求之前

在仓库中运行（./ready_to_pr.sh 会运行 moon fmt、moon check、moon test 和 moon info）：

moon fmt
moon check --target all
moon test
moon info

审查每个 pkg.generated.mbti 的差异：它是公开 API 的权威来源，其中的任何变化都是 API 变化，文档和变更日志必须反映出来。

代码风格

• 用 moon fmt 格式化；顶层项之间用 ///| 分隔。
• 绑定、函数、文件和文件夹使用 snake_case，类型和 trait 使用 PascalCase。文件按其实现的内容命名（sparse_polynomial.mbt），而不是 utils.mbt。
• 显式的方法提升（pub extend T with Trait::{...}）放在 extends.mbt 中。提升运算符、equal、compare、hash 和规范的 to_string；其他 trait 方法只通过 trait 提供，兼容性提升标记为 #deprecated 和 #doc(hidden)。
• 在黑盒测试中，被测包的名字要加限定（@immut.DensePolynomial）；白盒测试（*_wbtest.mbt）可以不加限定地使用它们。

库约定

• 规范形式。 每个公开操作都返回规范值：修剪过的稠密向量、严格降序且已合并的项数组、不含零的稀疏映射。新操作必须在返回前恢复该不变量。
• 最小约束。 每个函数只要求它所用到的 luna-generic 能力。
• 带检查的变体。 部分操作有一个会中止的形式，以及一个在违反契约时返回 None 的 *_checked 形式。中止消息要指出被违反的契约。
• 两层。 先在 immut 中添加操作；再以相同的名字和参数顺序添加可变版本，除非原地存储能带来实际好处，否则委托给 immut，并在 src/consistency 中添加检查。在 mutable 设计中记录每一处有意的差异。
• 变更须显式命名。 只有 setter、clear、add_term_inplace 和 *_inplace 方法可以修改其接收者。

文档

手册遵循 Luna Flow 文档标准：英文页面位于 doc/manual（每个包各有一个 api/、design/ 和 tutorial/ 页面，以包路径命名），中文和日文翻译以 gettext 目录的形式位于 doc/locale。编辑英文页面后，运行 lunadoc update 并翻译新的或模糊（fuzzy）的消息。每个可运行的 moonbit 代码块都必须能针对当前代码编译通过；有意保留的片段标记为 moonbit nocheck。

提交

使用英文的 Conventional Commits，<type>(<scope>): <subject>，以包作为 scope（fix(immut/context): ...），每个提交只包含一个逻辑变更。如果你不是维护者，在修改依赖或 moon.mod 中的版本之前请先询问。