贡献规范

致贡献者

我们热烈欢迎熟悉线性规划与优化库的开发者加入本项目，贡献代码并分享宝贵经验。同时，我们也鼓励初学者通过参与开发和完善文档来学习线性规划方法。我们希望，无论是经验丰富的开发者还是初学者，都能通过阅读项目的文档、表格和代码示例，找到自己感兴趣的贡献目标。

我们衷心感谢所有为本项目做出贡献的开发者。无论是提交代码、完善文档，还是提供宝贵的反馈，你的每一份努力都让这个项目变得更好。你们在开发过程中的热情与智慧不断推动项目前进，也为社区带来了更多合作的机会。感谢你们的支持与付出，期待与大家携手取得更多成果，让这个项目迎来更加光明的未来！

1. 代码风格

统一采用 MoonBit Toolchain 的格式化风格，通过运行以下命令来自动格式化代码。
```
moon fmt
```
请确保在提交代码之前，使用 moon fmt 格式化代码，以保持一致的代码风格。

或者，可以使用 ready_to_pr.sh 脚本来自动格式化代码、运行检查、生成测试覆盖率文件和 .mbti 文件。

2. 命名约定

2.1 变量命名

采用 小写字母和下划线 分隔（例如：my_var）。
变量名应具有描述性，能够准确反映其用途。

2.2 函数命名

使用 小写字母和下划线 分隔（例如：calc_total_price()）。
函数名应简洁且具有描述性，能够清晰表达函数的功能。

2.3 Struct 和 Trait 命名

使用 首字母大写的驼峰式命名（例如：MyStruct、MyTrait）。
命名应直观地反映该结构体或特征的功能或角色，避免使用过于抽象或不具描述性的名称。

2.4 常量命名

注意： 由于在 MoonBit 的语境下，“变量”通常称为“binding”，且默认是不可变的，只有添加 mut 关键字才能使其可变。因此，常量和“变量”之间没有严格的命名差异，保持一致性。
常量名采用 全小写字母和下划线 分隔（例如：machine_dbl_epsilon）。
常量名通常以第一个单词作为前缀，表示常量的用途或分类。例如，machine_dbl_epsilon 中的 machine 表示与机器相关的常量。
常量名应简洁且具有描述性，便于其他开发者理解。

2.5 Result 的 Err 构造内容和 Err Code

采用 全大写字母和下划线 分隔（例如：E_MAX_ITER）。
构造内容通常以字符E作为前缀，表示其用于 Err 构造或者错误代码。
构造内容应简洁且具有描述性，便于其他开发者理解。

3. 注释

简洁性：注释应简洁明了，只包含必要的信息，避免冗长和不相关的内容。
一致性：使用一致的术语和风格，避免在不同地方使用不同的方式描述相同的概念。
清晰性：确保注释易于理解，避免复杂的术语或模糊的表述。应使任何阅读代码的人能够快速理解注释的意图。
准确性：注释必须准确反映代码的功能和目的，避免与代码行为不符的描述。
更新性：随着代码的变更，注释也应随时更新，确保注释与代码同步。

我们鼓励开发者采用 MoonBit LSP 提供的 AI 代码注释生成来提升注释的编写效率，但需要开发者对 AI 生成的内容进行审核，以确保其对方法、结构体和特征的解释是正确无误的。

4. 文件规范

4.1 文件夹命名

对于大的功能模块，请使用小写字母命名的文件夹（包）。
文件夹名称应简洁、具有描述性，并使用下划线（_）分隔单词。请避免使用数字和特殊字符。

4.2 文件划分

文件应该按功能划分，每个文件专注于特定的功能。文件名使用小写字母和下划线。
文件名应具备描述性，清楚反映该文件所实现的核心功能。

例如：
- constraint.mbt：实现线性规划的约束。
- objfunc.mbt：实现目标函数。
注意：在文件命名中（除了在@internal 中不可避免的情况），请避免使用过于通用或模糊的名称，如 utils.mbt，请尽量使文件名与其功能或模块相关联。

5. 提交规范

5.1 提交信息

在提交前请使用 ready_to_pr.sh 脚本来自动格式化代码、运行检查、生成测试覆盖率文件和 .mbti 文件。
每个提交应具有清晰的描述，说明此次提交所做的变更。
提交信息应使用英文，并遵循简短、精炼的原则。

使用 fix:，feat:，refactor: 和 doc: 等前缀来区分提交的类型

例如：

fix: fix bug in something
feat: add feature for something
refactor: refactor something
doc: add docs for something

5.2 提交频率

尽量保持每次提交都很小且聚焦于一个功能或修复。
不要一次性提交大规模的更改。

6. 代码审查

非项目维护者和合作者在修改moon.mod内的依赖和版本号前，请先联系维护者或者合作者。
所有的代码提交都必须经过代码审查。
在审查过程中，关注代码质量、风格、性能和安全性。
审查者应提供建设性的反馈，帮助改进代码。