Mojo 贡献区域指南：编译器与标准库的贡献边界与实操路径

Mojo 贡献区域指南：编译器与标准库的贡献边界与实操路径

【免费下载链接】mojoThe Modular Platform (includes MAX & Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo

本文档基于 Mojo 开源仓库的 contribution-areas.md 编写，聚焦 Mojo 项目当前开放的贡献区域：编译器与标准库分别接受哪些类型的改动、拒绝哪些类型的改动，以及重大变更应走的 proposal 流程。阅读本文后，你将能在动手写代码之前准确判断"我想改的部分是否被接受、以何种方式参与"，并掌握标准库开发与测试的入门命令。

Mojo 项目（The Modular Platform，包含 MAX 与 Mojo）以渐进方式开放社区贡献：团队计划逐步扩展接受的贡献类型，以便在贡献流程逐步成熟的同时，让 Modular 团队能够适应持续增长的输入与随之而来的评审负担。因此，当前仓库对"哪些代码区域可以贡献、每种区域接受哪种改动"有明确划分。在开始任何工作之前，请先核对你想改进的代码库部分是否在本指南覆盖范围内，然后遵循 贡献流程 提交变更。

一、总体框架：渐进式开放的贡献策略

从仓库的贡献文档体系可以看出，Mojo 的社区参与被划分为多个层次：

• 阅读与构建源码：所有区域均开放，任何人都可以阅读、构建并提交 issue；
• 提交代码（Pull Request）：仅标准库区域开放，编译器暂不接受 PR；
• 提交重大设计变更：通过 proposal 流程 提交书面提案。

这一分层策略的核心考量在 contributing/README.md 中有完整索引：它先让社区通过 issue、讨论和文档学习项目，再逐步开放代码合入通道，以保证评审质量与维护者的精力分配。从仓库结构看，Mojo/ 目录同时承载了编译器（Mojo/lib/Compiler、Mojo/lib/MojoParser等）与标准库（Mojo/stdlib/std）两大部分，贡献者需要先明确自己的目标区域。

二、编译器区域：暂不接收 PR，但欢迎深入源码与提交 issue

2.1 当前状态

编译器目前不接受贡献（不接收 Pull Request）。但源码是开放的，社区成员完全可以：

• 阅读源码：编译器相关文档位于 compiler/README.md，它进一步指引到 Mojo/docs/compiler 下的编译器文档体系，其中 WorkingInOSRepo.md 讲解了在开源仓库中构建 Mojo 编译器的构建标志、Bazel 别名与示例命令，是新手最先应读的文档；
• 构建编译器：按照编译器贡献文档执行./bazelw系列构建命令；
• 提交 bug 报告：在 issue 追踪器中提交，并遵循 issue 与 PR 规范。

2.2 参与编译器的正确方式

尽管不接收 PR，bug 报告仍然非常有价值。提交 bug 时请遵循 issue 与 PR 规范，确保报告包含足够的信息以便复现。从仓库源码结构看，编译器代码分布在Mojo/lib下的多个方言与转换目录（如Mojo/lib/Transforms、Mojo/lib/KGENDialect、Mojo/lib/HLCFDialect等），编译器测试 文档说明了FileCheck约定与编写编译器测试的准则——"每个 bug 修复都需要一个测试"是编译器团队的核心要求。

提示：贡献区域的状态会随项目发展而变化。开始工作前，始终先查看最新版 contribution-areas.md 确认编译器区域是否已开放 PR。

三、标准库区域：当前唯一开放代码合入的区域

标准库团队目前接受以下类型的变更：

3.1 接受的变更类型

从仓库实际内容看，标准库位于 Mojo/stdlib/std，包含algorithm、bit、builtin、collections、math、memory、testing等 30 余个模块；对应的测试位于 Mojo/stdlib/test。例如 test_bit.mojo 等测试文件大量使用assert_true、assert_eq等来自testing模块的断言函数，这正是"从 FileCheck 迁移到assert_*"这一接受项的落地形态——标准库的单元测试如今以 Mojo 断言为主，而非文本匹配。

3.2 不接受的变更类型（非穷尽清单）

以下类型的变更不被接受，请避免提交：

• 与已发布的路线图或标准库核心原则不符的变更；
• 对math模块的改动（直到更全面的性能基准测试可用为止）；
• 没有测试的代码，尤其是核心原语（core primitives）；
• 破坏现有 API 或隐式行为语义的变更；
• 某位贡献者因个人偏好而单方面将项目切换到自己偏好的功能或系统；
• 增加对冷门平台（esoteric platforms）的支持；
• 为代码库增加依赖；
• 大规模格式化或重构类变更；
• 需要广泛社区共识才能决定的变更；
• 贡献者不响应评审反馈的变更；
• 未经 proposal 流程就整体新增模块。

从源码结构看，标准库被明确定义为"叶子依赖"（leaf dependency）：stdlib-code-style.md 明确指出"不得向stdlib模块添加依赖，因为它按定义必须保持叶子依赖"。这解释了"增加依赖"为何被列入不接受清单——它直接违背标准库的架构约束。

3.3 重大变更：先走 proposal 流程

如果你希望进行更重要的改动（例如新增一个完整的模块），第一步是撰写书面提案，流程详见 proposal-process.md：提案是以 GitHub Pull Request 形式向proposals/目录添加一份文档。仓库中已积累了大量提案文档（Mojo/proposals），涵盖value-ownership.md、lifetimes-and-provenance.md、enums.md、pattern-matching.md、variadics-design.md等语言与标准库的关键设计，这些文档同时充当了过去决策的审计日志，记录每一项设计背后的理由。

提案由 Mojo 标准库负责人决定是否接受：一旦指定的负责人批准、所有阻塞问题均已解决、相关决策已纳入，提案 PR 即可合并；若被推迟或拒绝，评审负责人会说明原因并关闭 PR。团队目标是提交后六周内完成评审与讨论——提案的评审周期通常比普通代码变更更长，因为需要与整体战略和愿景对齐。

四、深入标准库开发：从环境准备到测试提交

确定你的改动属于"接受的变更类型"后，即可进入标准库的实际开发。以下要点来自 stdlib-development.md 与 stdlib-code-style.md：

4.1 构建与测试

仓库使用 Bazel 构建，支持本地编译 Mojo 编译器或使用预构建编译器两种模式：

# 使用预构建 Mojo 编译器（写入 local.bazelrc 后无需重复传参） build --config=prebuilt-mojo

# 构建标准库 ./bazelw build //Mojo/stdlib/... # 运行标准库全部测试 ./bazelw test //Mojo/stdlib/test/... # 仅运行某个子目录的测试 ./bazelw test //Mojo/stdlib/test/math/... # 列出所有测试目标 ./bazelw query 'tests(//Mojo/stdlib/...)'

测试以启用断言的模式构建（-D ASSERT=all），会激活标准库中所有debug_assert，因此某个测试可能因发布构建会跳过的断言而失败；单个测试文件可通过BUILD.bazel中的_DISABLED_ASSERTIONS列表选择退出。如果安装了pixi，还可使用便捷脚本：

pixi run tests ./stdlib/test/bit pixi run tests ./stdlib/test/bit/test_bit.mojo

4.2 格式化与文档校验

提交 PR 前必须格式化代码，否则 CI 的 lint 与格式检查会失败：

./bazelw run //:format

推荐配置pre-commit钩子在每次提交时自动格式化：

pre-commit install # 或 pixi x pre-commit install / uvx pre-commit install

标准库代码还需通过文档字符串校验（不应有任何警告）：

mojo doc --diagnose-missing-doc-strings -Werror -o /dev/null stdlib/src/

4.3 代码风格要点

stdlib-code-style.md 规定标准库文件以src、test、docs、scripts组织，所有 Mojo 源文件必须以.mojo扩展名结尾；默认遵循mojo format的输出；每个文件需包含 Apache License v2.0 with LLVM Exceptions 的许可头；结构体方法之间使用统一的头部注释分隔约定。

五、优先事项：理解项目的前进方向

在投入精力之前，建议先了解 Modular 团队的优先事项：

• 愿景文档（vision）描述了指导团队工作的基本原则；
• 路线图（roadmap）明确了短期、中期和长期的具体开发目标。

在仓库内，Mojo/docs/contributing/README.md还索引了更多贡献文档：标准库 FAQ（faq.md，涵盖平台支持、MLIR 方言、编译器运行时等问题）、docstring 风格指南（docstring-style-guide.md）以及新增 GPU 目标指南（adding-gpu-targets.md）。

六、总结：动手前的检查清单

1. 确认区域开放：你的目标代码区域是否在贡献区域内？编译器暂不接收 PR，标准库开放；
2. 确认变更类型：你的改动属于标准库"接受的六类变更"吗？math模块改动、无测试代码、新增依赖等均不被接受；
3. 信号化意图：在 GitHub issue 上描述你要修复的 bug 或新增的功能，搜索既有 issue 避免重复；
4. 重大变更走提案：新增完整模块等改动需先提交 proposal 到Mojo/proposals目录；
5. 测试与格式：附带合理测试覆盖，运行./bazelw test //Mojo/stdlib/test/...与./bazelw run //:format，再按 贡献流程 提交 PR。

遵循上述边界与流程，你的贡献才能顺利通过评审、合并并在下一个 nightly 版本中发布。

【免费下载链接】mojoThe Modular Platform (includes MAX & Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo