贡献指南

本指南汇集了修改 luna-complex 时应遵循的规则。提交拉取请求前请运行 ./ready_to_pr.sh。

代码风格

• 所有代码统一使用 moon fmt 格式化。
• 优先使用 src/alias.mbt 和 src/float_backend/alias.mbt 中共享的 using 导入，而不是反复写完全限定调用。
• 注释应简短且技术化。注释用于解释数值稳定性的取舍、分支选择或不明显的约定；不要复述代码。
• 在 src/extends.mbt 中显式提升 trait 方法；已弃用的方法形式保留在那里，并带有 #deprecated 和 #doc(hidden)。

命名

• 绑定与函数：小写加下划线，如 pow_real。
• 类型与 trait：PascalCase，如 Complex 或 FloatingBackendScalar。
• 文件：小写加下划线，按其负责的行为命名。避免 utils.mbt 这类大杂烩文件。

包边界

• 根包负责泛型的 Complex[T]：构造、修改、代数运算以及 luna-generic 实例。它不包含任何浮点语义。
• src/float_backend 负责浮点能力 trait 与解析函数。按照当前 MoonBit 的规则，一个包不能为另一个包的类型添加方法或 trait 实例，因此这些都是自由函数。
• 仅当该构造在所述约束下满足相应定律时，才为 Complex[T] 添加实例；参见核心设计。
• 公开 API 的变更须经过深思熟虑；内部辅助函数保持私有。

数值相关的修改

• 在 float_backend 设计中写明公式以及任何重新缩放或特殊情形的理由，并在 float_backend API 中写明可观察到的分支与特殊值行为。
• 为每一项改变的数值行为添加回归测试：如 exp(log z) = z 之类的恒等式、分支切割线上及其附近的值、极大与极小的输入，以及特殊值。

测试要求

• 黑盒测试位于代码旁的 *_test.mbt 中，并使用限定名，如 @luna-complex.Complex::new。
• 对所有行为发生变化的目标运行 moon test，提交前运行 moon test --enable-coverage。
• 公开 API 变化时，用 moon info 重新生成 pkg.generated.mbti，并检查其差异。

文档

• 手册位于 doc/manual。修改英文页面后，运行 lunadoc update 并更新 doc/locale 中的中文和日文翻译目录。
• 手册中的代码示例必须能针对当前代码编译通过。

提交与发布

• 使用英文的 Conventional Commits，例如 fix(float_backend): use pi on the negative real axis。
• 每次提交只聚焦一个逻辑变更。
• 发布前，更新 moon.mod 中的版本号，更新 README.md 和 CHANGELOG.md，运行 moon check 和 moon test --enable-coverage，并使用与 moon.mod 完全一致的版本号触发发布工作流。
• 如果你不是维护者，修改 moon.mod 中的依赖或版本声明前请先询问。