MLSysBook 仓库贡献完整指南：项目路由、dev 分支工作流与 pre-commit 质量门禁
【免费下载链接】cs249r_bookMachine Learning Systems项目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_book
MLSysBook（即 cs249r_book 仓库）是Machine Learning Systems 教科书与其姊妹项目（TinyTorch、Co-Labs、Hardware Kits、MLSys·im、MLPerf EDU、StaffML 等）的聚合仓库（monorepo）。本指南以仓库根目录的 CONTRIBUTING.md 为骨架，完整覆盖"选择贡献项目 → 分支 → 本地校验 → 提 PR → 获得致谢"的全流程，并结合仓库内的 .pre-commit-config.yaml、.github/PULL_REQUEST_TEMPLATE.md 与 CI 工作流，给出可逐条验证的源码级依据。读完你就能在正确的位置、用正确的工作流，向这个仓库提交第一份合格贡献。
仓库全景：一个 monorepo，九个"贡献落点"
仓库根目录的 CONTRIBUTING.md 开宗明义：本仓库是ML Systems 教科书加一族姊妹项目的家，绝大多数贡献只会落在其中一个项目里，因此这份顶层指南的职责是"把你送到正确的地方"。
- 教科书（Textbook）：书稿主体，各章节的 qmd 源文件、配图、练习；
- TinyTorch：从零实现的深度学习框架（模块、测试、里程碑）；
- Hardware Kits：硬件实验与板卡配方；
- Co-Labs：基于 Marimo + Pyodide 的浏览器交互实验；
- MLSys·im：ML 系统模拟器（模型、场景、评分卡）；
- MLPerf EDU：教学用基准测试套件；
- StaffML：面试题库语料库与站点（位于
interviews/，其子项目指南见 interviews/CONTRIBUTING.md）； - Instructors：教学材料、大纲与评分标准；
- Slides：各章节配套幻灯片；
- Site：统一落地页、Newsletter 与游戏。
顶层指南还给出了一条关键前置提醒：贡献前请先阅读 CODE_OF_CONDUCT.md；安全问题应走 SECURITY.md，而不要走公开的 issue 跟踪器。
第一步：选择你要贡献的项目
下面的路由表是这份指南的核心，它把"你想做的事"映射到"该去读哪个项目文档"：
| 你想做的事 | 项目 | 应阅读的指南 |
|---|---|---|
| 修错别字、改进章节、新增配图 | 教科书 | book/docs/CONTRIBUTING.md |
| 新增或修复 TinyTorch 模块 / 测试 / 里程碑 | TinyTorch | tinytorch/CONTRIBUTING.md |
| 改进硬件实验或板卡配方 | Hardware Kits | kits/README.md |
| 新增或修复交互式 Co-Lab | Labs | labs/README.md |
| 贡献 MLSys·im 模型、场景或评分卡 | MLSys·im | mlsysim/docs/contributing.qmd |
| 向 MLPerf EDU 基准套件新增工作负载 | MLPerf EDU | mlperf-edu/README.md |
| 编写或修复 StaffML 面试题 | StaffML | interviews/CONTRIBUTING.md |
| 改进教学材料、大纲或评分标准 | Instructors | instructors/README.md |
| 为某一章更新幻灯片 | Slides | slides/README.md |
| 修改统一落地页、Newsletter 接线或小游戏 | Site | site/README.md |
如果拿不准该归哪个项目，可以在 GitHub 的Discussions里发帖求助，维护者会帮你路由。
新手最容易踩的坑（Common Gotchas）
这部分列出了"光读某个子项目 README 看不出来"的隐性约定，每一条都指向权威文档而不是重复叙述：
- TinyTorch 的一切都走
titoCLI：模块状态、测试、导出、环境健康检查全部经由tito完成——tito --version、tito system health、tito module status、tito module test NN。如果pip install -e tinytorch/之后tito不在 PATH 上，请重新激活你的虚拟环境（venv）。 - TinyTorch 源码修改需要导出步骤：当你修改
tinytorch/src/下的文件时，tinytorch/tinytorch/下的包内副本由tito dev export重新生成（详见tinytorch/CONTRIBUTING.md的 "Module Development" 一节）。tinytorch/tinytorch/*被 gitignore，真正的源是src/——不要直接改包内副本。 - Co-Labs 通过 Pyodide / WebAssembly 在浏览器中运行：import 必须与 Pyodide 兼容（没有 wheel 的纯编译包不行），并且每个产生 UI 元素的 Marimo cell 都必须
return该元素，数据流才能继续向后路由——这是labs/PROTOCOL.md中的发布不变量 #4，实验室测试套件会强制这两条。 - 不要提交大型二进制文件：发布的 PDF、EPUB、播客 MP3 和 JS bundle 会让
.git急剧膨胀。根目录的.gitattributes已做配置，未来新增的 EPUB / PDF / MP3 / MP4 / WAV / WASM 会自动落入 Git LFS；生成物（bundle.js、corpus.json、搜索索引）已被 gitignore，应在本地重新生成而不是提交。需要提醒的是：在当前这份检出的根目录 .gitattributes 中，已明确注明 "Git LFS is no longer used in this repo"，二进制文件直接入库，LFS 规则与正文描述存在差异——提交大文件前请以当前
.gitattributes实际内容为准。 - 各区域的位置以路由表为准：一览——
book/放教科书，tinytorch/放框架，labs/放浏览器实验，kits/放硬件配方，mlsysim/放模拟器，instructors/放教学材料，slides/放章节 deck，interviews/放 StaffML，site/放统一落地页与 Newsletter。
通用规范：适用于所有子项目的六条约定
1. 从dev分支出发，而不是main
main跟踪已发布的线上站点。所有工作先合并进dev，发布时才推进到main：
git checkout dev git pull origin dev git checkout -b iss123-short-descriptive-slug分支名应引用 issue 编号（存在时），例如iss42-fix-figure-caption、feat/tinytorch-conv-module。
2. 配置 pre-commit 钩子（每个克隆只做一次）
这个仓库运行约 60 项 pre-commit 检查（BibTeX 校验、figure-div 语法、Markdown 链接检查、EPUB 卫生检查、vault schema 漂移检测等），定义在根目录 .pre-commit-config.yaml 中。它们能拦截掉本会消耗维护者审查轮次的低级问题。每个全新克隆安装一次：
pip install pre-commit pre-commit install这一条对任何子项目都够用，默认钩子集只是根.pre-commit-config.yaml。TinyTorch 额外附带tinytorch/.pre-commit-config.yaml（markdown collapse、CLI 文档检查），需要时手动运行：
cd tinytorch && pre-commit run --config .pre-commit-config.yaml --all-files部分项目还有自己的环境初始化步骤（可能顺带替你接好 pre-commit）：
| 项目 | 项目专属初始化 |
|---|---|
| 教科书 | ./book/binder setup（同时安装 Quarto / Java / epubcheck 检查） |
| TinyTorch | pip install -r tinytorch/requirements.txt && pip install -e tinytorch/ |
| StaffML / vault-cli | pip install -e interviews/vault-cli/[dev] |
| MLSys·im | pip install -e mlsysim/[dev] |
| MLPerf EDU | pip install -e mlperf-edu/[dev] |
| StaffML 站点 | cd interviews/staffml && npm install |
源码佐证：在 .pre-commit-config.yaml 中，当前检出一共定义了 52 个钩子条目，覆盖四类能力：通用卫生（
trailing-whitespace、end-of-file-fixer、check-json、check-yaml、check-merge-conflict、check-added-large-files、detect-private-key、check-case-conflict、codespell）、书籍专用检查（book-check-bib、book-check-internal-links、book-check-figures、book-check-images、book-check-math、book-check-notation、book-check-epub等）、格式化工序（mdformat、bibtex-tidy、book-format-python等）以及跨项目一致性检查（mlsysim-check-registry-gates、vault-schema-drift、ci-check-workflow-fork-safety、ruff）。
3. 显式暂存文件，不要git add .
禁止使用git add .——很容易把无关修改、密钥或构建产物一起提交。应逐个指定路径：
git add book/quarto/contents/vol1/introduction/introduction.qmd git commit -m "Fix caption formatting in introduction (issue #14)"4. 向dev提交 Pull Request
- 在 PR 描述中引用 issue 编号（
Fixes #123或Related to #456）； - 草稿用
[WIP]前缀标题，或使用 GitHub 的 "Draft PR" 模式； - 使用 PR 模板——它提出的正是评审者本来也会问的问题；
- CI 会渲染受影响的子项目（book / tinytorch / staffml 等），请求评审前务必修复任何失败。
源码佐证：仓库的 .github/PULL_REQUEST_TEMPLATE.md 定义了标准 PR 结构：
Summary（1–3 句）、Area勾选区（Book / TinyTorch / StaffML / Kits / Infrastructure）、Changes、Testing勾选区（quarto render、pytest tests/、tito module test NN、手动验证）与Related Issues。Testing区还内置了"提交即视为同意按项目许可证发布贡献"的声明。与此同时，.github/workflows/ 下按子项目成对出现*-validate-dev.yml、*-preview-dev.yml、*-publish-live.yml（如book-validate-dev.yml、tinytorch-validate-dev.yml、staffml-validate-dev.yml、mlsysim-pypi-publish.yml），印证了"CI 渲染受影响项目"的说法：dev 分支校验、预览、发布三阶段流水线对每个子项目都是独立可追踪的。
5. 行为准则（Code of Conduct）
提交贡献即表示同意遵守 Contributor Covenant Code of Conduct。问题可通过vj@eecs.harvard.edu或nkhoshnevis@g.harvard.edu反映。
6. 贡献的许可证
提交 PR 即表示同意将贡献置于项目的许可证之下：内容部分采用 Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International（CC BY-NC-SA 4.0），代码组件按各子项目本地条款双重许可（详见每个子项目自己的LICENSE）。
报告 Bug 与提问：三个入口的取舍
顶层指南给出了三种诉求的明确分流：
- 发现真 Bug 或具体问题→ 打开 issue，使用与场景匹配的模板。仓库 .github/ISSUE_TEMPLATE/ 下实际存在 8 个模板：
bug_report.yml、tinytorch_improvement.yml、mlsysim_bug.yml、new_challenge.yml、interview_question.yml、staffml_report.yml、staffml_contribute.yml以及一个404_joke.yml（另有config.yml控制模板入口），覆盖"书稿、TinyTorch bug、MLSys·im bug、新挑战题、面试题、StaffML 报告/贡献"等场景，与正文"我们有八个模板"的描述吻合。 - 一般性问题或设计讨论→ 更适合放到Discussions。
- 安全问题→ 走 SECURITY.md，不要开公开 issue。
贡献者致谢：All Contributors 机器人
项目使用 All Contributors 机器人。PR 合并后，维护者（或你在自己的 PR 上）可以评论：
@all-contributors please add @your-username for doc, code, ideas随后你会被加入 README 中的致谢表。完整的贡献类型列表见book/docs/CONTRIBUTING.md的 "Contribution Types" 一节。仓库根目录的 .all-contributorsrc 以及.github/workflows/下的all-contributors-add.yml、all-contributors-auto-credit.yml、update-contributors.yml三个工作流，共同实现了这套自动致谢机制。
纵深参考：子项目指南的完整工作流示例
顶层指南是"路由中枢"，真正细化的开发循环在各子项目指南里。以仓库中实际存在的 interviews/CONTRIBUTING.md 为例，可以看到"顶层路由 + 子项目细化"的完整形态：它给出 clone → 安装vault-cli（pip install -e vault-cli/[dev]）→vault build→ 本地 API shim（vault api --db interviews/vault/vault.db --port 8002）→ 启动站点的十分钟上手路径；开 PR 前必须跑vault check --strict、pytest vault-cli/tests/与vault codegen --check；并定义了 4 条"阻断外部 PR 合并"的红线（provenance 造假、修改 append-only 的id-registry.yaml、同一 PR 混用不同schema_version、未签名的 schema 演进 PR）。这种"顶层路由表 + 子项目纵深文档"的分层结构，正是本仓库贡献体系的设计核心。
小结
一份合格的 MLSysBook 贡献，遵循的就是这条可复现的路径：先读路由表确定落点 → 从dev拉出新分支 → 装上根 pre-commit 钩子（必要时补子项目专属初始化）→ 显式暂存改动 → 用 PR 模板向dev开 PR 并过掉 CI → 合并后由 All Contributors 记录致谢。其中"约 60 项 pre-commit 检查"对应到 .pre-commit-config.yaml 里实际可数的 52 个钩子，"CI 渲染受影响项目"对应到.github/workflows/里按子项目成对存在的 validate / preview / publish 流水线，"八个 issue 模板"对应到 .github/ISSUE_TEMPLATE/ 里真实存在的 8 个 yml 文件。社区正是靠着"有人改一个错别字、报一个好 bug、写一份谨慎的 PR"运转起来的——你的第一份贡献，就从选择一个落点开始。
【免费下载链接】cs249r_bookMachine Learning Systems项目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_book
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
