ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

pyprobml 代码贡献指南:从 Issue 到 Pull Request 的开源协作流程与编码规范详解

pyprobml 代码贡献指南:从 Issue 到 Pull Request 的开源协作流程与编码规范详解 机器学习深度学习【免费下载链接】pyprobmlPython code for Probabilistic Machine learning book by Kevin Murphy项目地址https://gitcode.com/gh_mirrors/py/pyprobml点击查看免费下载pyprobml 是 Kevin Murphy 的《Probabilistic Machine Learning》系列图书书 1《An Introduction》与书 2《Advanced Topics》配套的 Python 3 复现代码仓库。本文基于仓库根目录的 CONTRIBUTING.md 展开系统讲解向该仓库贡献代码的完整协作流程——从 MIT 贡献者协议、Python 编码规范与 JAX/Flax 技术选型到 Issue 驱动的开发模式和 Pull Request 提交规范并结合仓库内的测试、配置与目录结构给出源码级佐证。读完本文你将掌握如何在 pyprobml 中安全地提出新功能、规范地提交代码并通过审查同时避免踩中常见的协作雷区。项目背景为 Probabilistic ML 图书的图表复现代码做贡献pyprobml 的目标是用 Python 3 复现《Probabilistic Machine Learning》两本图书中的全部图表代码以 Jupyter Notebook 为主体、以可执行脚本为补充。根据 README.md 的说明代码主要依赖 numpy、scipy、matplotlib、sklearn 等标准 Python 库书 2 的部分代码使用 JAX书 1 的部分代码使用 TensorFlow 2 和少量 Torch。自 2022 年 9 月起仓库进入维护模式maintenance mode这意味着贡献者应当以修复缺陷、完善现有内容为主要目标而不是大规模重构。CONTRIBUTING.md 由 Kevin Murphy、Mahmoud Soliman 和 Zeel B Patel 维护最后更新于 2022-05-03。该文档明确欢迎社区提交补丁patches与贡献并声明项目遵循 Google 的开源社区准则。全文围绕两条主线展开编码规范Coding guidelines与GitHub 协作流程Github guidelines下面逐一展开。贡献者许可协议以 MIT 许可发布贡献向 pyprobml 提交任何贡献即代表贡献者同意将其贡献内容以MIT 许可发布。仓库根目录的 LICENSE.txt 即为此协议的落点。这一条款是提交代码前的法律前提你的代码一旦合入就与仓库主体一样在 MIT 许可下开放使用、修改与再分发。对首次参与开源的同学这里无需额外签署纸质协议提交 Pull Request 即视为同意该条款。编码规范Python 风格、命名约定与技术栈选型CONTRIBUTING.md 的编码规范部分给贡献者划定了三条硬性红线直接影响你的代码能否顺利通过审查。遵循 Google Python 风格指南与 PEP8 命名约定贡献者应当遵循Google Python 风格指南尤其要严格遵守PEP8 命名约定函数名与变量名使用小写加下划线的 snake_case类名使用 CapWords 等。仓库中数以百计的脚本即是活生生的范例——例如 scripts/softmax_plot.py、scripts/mix_gauss_mle_vs_map_jax.py、scripts/autodiff_demo_jax.py 等均采用小写加下划线的命名方式。此外仓库根目录的 pyproject.toml 通过 Black 配置将行宽固定为 120 字符line-length 120这是代码格式化层面的具体约定贡献者提交前可用 Black 按此配置格式化自己的代码。关于 Python 使用规范仓库在 notebooks/tutorials/python_tutorials.md 中维护了一份 Python 教程列表供贡献者参考学习。技术栈约定数值计算用 JAX神经网络用 FlaxCONTRIBUTING.md 给出两条明确的技术选型指令使用 JAX 替代 numpy/scipy新增数值计算代码时优先使用 JAX 而不是 numpy/scipy。仓库在 notebooks/tutorials/jax_tutorials.md 中整理了完整的 JAX 入门资料并在 notebooks/tutorials/jax_intro.ipynb、notebooks/tutorials/practical_jax_tips.ipynb 等教程 notebook 中提供上手指引。仓库中大量脚本如 scripts/autodiff_demo_jax.py、scripts/gibbs_potts_demo_jax.py、scripts/mix_gauss_mle_vs_map_jax.py都以 JAX 为后端实现体现了这一约定在实战中的落地。神经网络使用 Flax 替代 PyTorch/TF如果贡献内容需要构建神经网络应使用 Flax 而非 PyTorch 或 TensorFlow。仓库中 scripts/vae_conv_mnist_flax_main.py、scripts/vae_conv_celeba_flax_main.py 以及 notebooks/book1/ 中的 lecun1989_flax.ipynb 等均为 Flax 实现的范例。需要说明的是这些选型约束主要面向新增代码仓库中既有的 TensorFlow/Torch 代码如书 1 的部分章节属于历史存量贡献者无需改写既有实现。依赖管理只添加 Colab 预装模块这一点虽未直接写入 CONTRIBUTING.md但体现在依赖文件的设计中requirements.txt 首行注释明确写着 add only those modules/libraries that are pre-installed in colab——即只允许添加 Google Colab 已预装的模块。当前依赖清单jaxlib、jax、jupyter、matplotlib、numpy、requests、scipy、seaborn、scikit-learn、h5py、pandas、graphviz、arviz、pyyaml全部满足该约束。原因在于 pyprobml 的核心使用场景之一是在 Colab 中直接运行 notebook一旦新增的依赖在 Colab 中不存在读者的复现体验就会被打断。因此贡献者在引入新依赖前务必确认目标模块属于 Colab 预装范围否则应设法绕开例如在 notebook 单元格内用try/except包裹可选导入。GitHub 协作流程Issue 驱动的开发模式CONTRIBUTING.md 用较大篇幅规范了 GitHub 侧的协作流程核心思想是一切提交以 Issue 为锚点。Issue 驱动的贡献模型提交必须响应已开放的 Issue原则上每一个 commit 都应对应一个已存在的 Issue。如果你想新增功能请先打开一个 Issue而不是直接提交代码。大 Issue 拆小部分 Issue 规模较大建议拆分成可单独攻克的小 Issue并在描述中链接回主 Issue便于维护者跟踪整体进度。认领 Issue 要出声想处理某个开放 Issue 时先在 Issue 评论区回复表明兴趣并附上任何设计文档或部分解决方案的链接避免多人重复开发同一内容。一次只做一个不要同时提交多个草稿 PRdraft PR集中精力逐个攻克。Pull Request 提交规范关联 Issue 必须写明如果 PR 对应某个开放 Issue务必在 PR 描述中使用 Issue 关键字如Fixes #123将其关联GitHub 会自动建立链接并在合入时关闭对应 Issue。只保留一个 commitPR 中应只有一个 commit。虽然维护者最终会 squash 合并但每多一个 commitGitHub 都会向所有关注仓库的人发送一封邮件通知造成不必要的打扰。提供图片预览代码生成的图表请通过公开的 gist 分享方便维护者快速目测eyeball输出是否符合书中预期请把 gist 链接附在 PR 中。这一点对图表复现类仓库尤其重要——维护者需要快速核对你生成的图与书中的图是否一致。PR 格式参考可参考仓库历史中格式规范的 PR 作为模板如果代码是存放在 fork 仓库中的 notebook请在 PR 中附上 notebook 的链接。审查与反馈周期代码就绪后请求以下三位维护者之一进行审查Kevin Murphymurphyk、Mahmoud SolimanmjsML和 Gerardo Duran-Martingerdm。CONTRIBUTING.md 承诺通常在 1–2 天内给出反馈。提交后请耐心等待若超时可在 PR 中礼貌提醒。了解仓库结构你的代码将落在哪里要写好贡献代码先要理解仓库的组织方式。结合 notebooks/README.md 与根目录 README.md仓库核心布局如下目录作用notebooks/book1/书 1《Probabilistic Machine Learning: An Introduction》各章节图表对应的 notebook按章节号01、02…23分子目录notebooks/book2/书 2《Probabilistic Machine Learning: Advanced Topics》各章节图表对应的 notebooknotebooks/tutorials/教学类 notebook讲解软件工具如 JAX、Pyro、NumPyro、pandas、sklearn 等不直接绑定图书章节notebooks/misc/未维护 notebook 的杂货间不属于正式内容scripts/独立可执行脚本多为单图 demo部分 notebook 由脚本组装生成tests/自动化测试import 检查与 notebook 执行测试deprecated/已弃用的旧版代码GAN、VAE 等不再维护贡献者新增 notebook 时应遵循此布局属于具体章节的放对应章节目录属于软件教学的放tutorials不要在misc中沉积无人维护的内容。测试与 CI提交前的自动化验证贡献代码前理解仓库的自动化测试体系有助于预判审查者的检查项。测试配置在 pytest.initestpaths tests主要包含两类测试tests/test_imports.py扫描notebooks/book1与notebooks/book2下所有 notebook 的全部单元格源码提取其中的import语句与当前环境中已安装的模块集合比对断言不存在缺失模块。该测试还从 internal/ignored_notebooks.txt 读取忽略清单被列入清单的 notebook 不参与检查。这意味着新增 notebook 不得引入环境中不存在的依赖与前述仅 Colab 预装模块的依赖约束相互呼应如果确有特殊依赖可通过 try/except 包裹导入测试代码专门解析了此类缩进包裹的 import或与维护者协商加入忽略清单。tests/test_notebooks.py借助 testbook 库以executeTrue模式真实执行notebook 全部分支单个 notebook 超时上限为 1200 秒TIMEOUT 1200。测试过程中设置FIG_DIR、DUAL_SAVE、LATEXIFY等环境变量以控制图表输出行为执行结果通过 tests/icons/right.png通过与 tests/icons/wrong.png失败两种图标标记到test_results目录失败时还会生成对应.log文件。该测试还支持通过PYPROBML_GA_RUNNER_ID环境变量将 notebook 列表分片便于在 GitHub Actions 中并行执行。简而言之你提交的 notebook 必须能在干净环境中顺利执行完毕这是进入主分支的硬门槛。贡献者在本地提交前应至少对新增脚本执行一次python3 脚本名.py冒烟运行对新增 notebook 执行一次完整运行确认无缺依赖、无异常报错。本地环境搭建安装依赖与快速复现贡献者需要先在本机搭建可复现环境。根目录 README.md 给出了几种安装方式其中与贡献者直接相关的做法是# 方式一直接从远程 requirements.txt 安装假设已自行装好 JAX / TensorFlow / Torch pip install -r https://raw.githubusercontent.com/probml/pyprobml/master/requirements.txt # 方式二下载 requirements.txt 到本地后安装 pip install -r requirements.txt # 方式三浅克隆仓库--depth 1 避免下载庞大的完整提交历史再手动安装 git clone --depth 1 https://gitcode.com/gh_mirrors/py/pyprobml注意事项JAX、TensorFlow、Torch 的安装依赖 CPU/GPU 等硬件环境README 建议贡献者根据自身硬件自行安装仓库的 requirements.txt 不包含这三者。若要保存生成的图表需要在执行前设置环境变量。README 给出的示例为import os os.environ[FIG_DIR] /teamspace/studios/this_studio/pyprobml/notebooks/figures os.environ[DUAL_SAVE] 1 # 同时保存 pdf 与 png其中FIG_DIR指定图片输出目录DUAL_SAVE1表示同时导出 PDF 与 PNG 两种格式。这套环境变量协议同样被 tests/test_notebooks.py 复用该测试中DUAL_SAVE与LATEXIFY被置空是贡献者本地复现图表时最常用的配置。提交前自检清单结合上文将 CONTRIBUTING.md 的要点浓缩为一张贡献者自检清单协议确认自己的贡献可接受 MIT 许可发布。流程是否已先开或认领IssuePR 描述是否用 Issue 关键字关联了对应 Issue粒度是否一次只处理一个 IssuePR 是否只有一个 commit代码Python 代码是否符合 PEP8/Google 风格snake_case、行宽 120数值计算是否优先 JAX神经网络是否用 Flax依赖新增依赖是否属于 Colab 预装范围对照 requirements.txt 清单验证notebook 能否完整执行参照 tests/test_notebooks.py 的执行要求所有 import 是否都能解析参照 tests/test_imports.py图片生成的图表是否已上传至公开 gist 并附在 PR 中方便维护者快速核对审查是否已请求 murphyk、mjsML、gerdm 中的一位进行 review按照这份清单提交你的 PR 将最大概率在 1–2 天内获得维护者反馈并顺利合入为《Probabilistic Machine Learning》的图表复现生态贡献一份可被后续读者复用的代码。赞分享机器学习深度学习【免费下载链接】pyprobmlPython code for Probabilistic Machine learning book by Kevin Murphy项目地址https://gitcode.com/gh_mirrors/py/pyprobml点击查看免费下载相关推荐R.swift 贡献指南Issue 协作流程、Pull Request 规范与源码/生成代码的编码原则R.swift 贡献指南Issue 协作流程、Pull Request 规范与源码/生成代码的编码原则 本篇指南以 R.swift 仓库的 Documenta开发工具代码生成CLI原生移动开源项目维护2048.cpp社区贡献与协作开发经验分享开源项目维护2048.cpp社区贡献与协作开发经验分享 2048.cpp是一个功能齐全的终端版2048游戏采用C编写。作为一个活跃的开源项目它的成功离kitti2bag实战从KITTI raw_synced数据到完整ROS bag的完整流程kitti2bag实战从KITTI raw_synced数据到完整ROS bag的完整流程 想要在ROS环境中使用KITTI数据集进行自动驾驶算法开发吗 k上一篇Argo Workflows REST API 完整指南认证模式、访问令牌与 53 个端点实战下一篇HugeJsonViewer轻松打开GB级JSON大文件的终极解决方案创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表