MLSysBook 仓库贡献完整指南：项目路由、dev 分支工作流与 pre-commit 质量门禁-北京尧图网络

MLSysBook 仓库贡献完整指南项目路由、dev 分支工作流与 pre-commit 质量门禁【免费下载链接】cs249r_bookMachine Learning Systems项目地址: https://gitcode.com/GitHub_Trending/cs/cs249r_bookMLSysBook即 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·imML 系统模拟器模型、场景、评分卡MLPerf EDU教学用基准测试套件StaffML面试题库语料库与站点位于interviews/其子项目指南见 interviews/CONTRIBUTING.mdInstructors教学材料、大纲与评分标准Slides各章节配套幻灯片Site统一落地页、Newsletter 与游戏。顶层指南还给出了一条关键前置提醒贡献前请先阅读 CODE_OF_CONDUCT.md安全问题应走 SECURITY.md而不要走公开的 issue 跟踪器。第一步选择你要贡献的项目下面的路由表是这份指南的核心它把你想做的事映射到该去读哪个项目文档你想做的事项目应阅读的指南修错别字、改进章节、新增配图教科书book/docs/CONTRIBUTING.md新增或修复 TinyTorch 模块 / 测试 / 里程碑TinyTorchtinytorch/CONTRIBUTING.md改进硬件实验或板卡配方Hardware Kitskits/README.md新增或修复交互式 Co-LabLabslabs/README.md贡献 MLSys·im 模型、场景或评分卡MLSys·immlsysim/docs/contributing.qmd向 MLPerf EDU 基准套件新增工作负载MLPerf EDUmlperf-edu/README.md编写或修复 StaffML 面试题StaffMLinterviews/CONTRIBUTING.md改进教学材料、大纲或评分标准Instructorsinstructors/README.md为某一章更新幻灯片Slidesslides/README.md修改统一落地页、Newsletter 接线或小游戏Sitesite/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/放章节 deckinterviews/放 StaffMLsite/放统一落地页与 Newsletter。通用规范适用于所有子项目的六条约定1. 从dev分支出发而不是mainmain跟踪已发布的线上站点。所有工作先合并进dev发布时才推进到maingit 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.yamlmarkdown collapse、CLI 文档检查需要时手动运行cd tinytorch pre-commit run --config .pre-commit-config.yaml --all-files部分项目还有自己的环境初始化步骤可能顺带替你接好 pre-commit项目项目专属初始化教科书./book/binder setup同时安装 Quarto / Java / epubcheck 检查TinyTorchpip install -r tinytorch/requirements.txt pip install -e tinytorch/StaffML / vault-clipip install -e interviews/vault-cli/[dev]MLSys·impip install -e mlsysim/[dev]MLPerf EDUpip 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 结构Summary1–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。问题可通过vjeecs.harvard.edu或nkhoshnevisg.harvard.edu反映。6. 贡献的许可证提交 PR 即表示同意将贡献置于项目的许可证之下内容部分采用 Creative Commons Attribution-NonCommercial-ShareAlike 4.0 InternationalCC 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-clipip install -e vault-cli/[dev]→vault build→ 本地 API shimvault 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），仅供参考

MLSysBook 仓库贡献完整指南：项目路由、dev 分支工作流与 pre-commit 质量门禁

相关推荐

AI辅助全栈开发：自建零代码平台的架构设计与运维实践

深入解析 libcurl 的 CURLOPT_SOCKOPTFUNCTION：在 socket 创建后、连接建立前定制套接字选项

ESP32声音采集实战：从ADC原理到事件识别

更多资讯

机动目标跟踪中运动模型失配的本质与IMM解决方案

Flutter CustomPaint 绘图原理与性能优化实战

野生动物AI监测系统：YOLO+SpringBoot工程落地全链路

赛事积分管理系统开发：从需求到部署的全栈实践

5分钟搭建 Supabase 数据库：从建表到 RLS 策略，为 Refine 管理后台备好后端

Netty长连接实战：校园互助社交APP服务端通信架构

今日更新

SpacetimeDB C++ 模块库实战：用 C++20 在数据库内构建 WebAssembly 模块

别踩雷！不是所有 AI 写作工具都靠谱，2026 高校认可工具精选

SSM+MySQL幼儿园管理系统源码解析：从部署到优化

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？