PyMC 开源贡献完整指南从个人提交到机构合作的全流程实践【免费下载链接】pymcBayesian Modeling and Probabilistic Programming in Python项目地址: https://gitcode.com/GitHub_Trending/py/pymcPyMC 是一个以 Python 编写的开源贝叶斯统计建模与概率编程框架其官方贡献指南docs/source/contributing/index.md明确了这是一个集体努力的项目任何人都可以以自己擅长的方式参与建设。本文以该指南为核心骨架完整梳理 PyMC 的贡献方式、Pull Request 全流程、代码礼仪、质量检查、测试运行、文档构建、开发环境搭建以及机构合作路径并结合仓库内真实源码与配置逐一佐证帮助你从想贡献到会贡献走通每一步。一、贡献方式的总体图景PyMC 是集体努力的开源项目PyMC 的贡献指南开宗明义地指出PyMC 是一个开源、集体努力的项目PyMC is an open source, collective effort有非常多的方式可以让它变得更好且所有方式都受到欢迎。编码coding和文档documentation是最常见的贡献类型但绝非全部——指南明确列出以下同样重要的非代码贡献方向报告 Bug 或提出改进建议通过 GitHub 的 issue 新建入口提交问题报告或改进提案在社区论坛回答问题帮助其他用户在 Discourse 论坛上解答疑问教学与传播最佳实践通过写博客或做演讲推广 PyMC 的正确用法参与 PyMCon 的策划PyMCon 是 PyMC 社区主办的科学会议推广与外联包括联系潜在的赞助公司、向可能在工作与学术研究中用得上 PyMC 的人介绍它以及确保使用 PyMC 的学者在论文中正确引用协助筹款工作为 PyMCon 的视频添加时间戳。指南特别提示如果还不确定自己能贡献什么、如何开始可以通过 Discourse 论坛联系团队也可以订阅office-hours标签参与定期举办的office hours获得面向贡献者的专门支持。对于刚接触开源的新手指南还推荐参考 sprint 材料——即使不参加 sprint 活动这套材料也是目前可用的最详细贡献入门指导。二、通过 Pull Request 贡献完整的分步教程代码与文档贡献都需要通过 GitHub 向 pymc-devs 组织下的仓库提交 Pull RequestPR。仓库中保存了完整的步骤化教程 docs/source/contributing/pr_tutorial.md推荐的工作流是fork 主仓库 → 克隆到本地 → 在 feature 分支上开发。其完整步骤如下先阅读代码贡献礼仪见下文第三节Fork 主仓库点击主仓库页面右上角的 Fork 按钮在你的 GitHub 账户下生成一份代码副本克隆并配置远程仓库git clone gitgithub.com:your GitHub handle/pymc.git cd pymc git remote add upstream gitgithub.com:pymc-devs/pymc.git其中upstream指向 pymc-devs 官方主仓库origin指向你自己的 fork创建 feature 分支git checkout -b my-feature注意始终使用 feature 分支。在任何仓库中都不应养成直接在main分支上工作的习惯搭建开发环境项目运行依赖在requirements.txt开发依赖在requirements-dev.txt。指南推荐使用 miniconda 通过 conda 环境文件一键创建Linux/MacOSconda env create -f conda-envs/environment-dev.ymlWindows 与 WindowsGit Bashconda env create -f conda-envs/windows-environment-dev.yml创建完成后激活环境并以可编辑模式安装本地包conda activate pymc-dev pip install -e .另一种等价方式是在虚拟环境中执行pip install -e .后再pip install -r requirements-dev.txt。从仓库结构看conda-envs/environment-dev.yml 与 conda-envs/windows-environment-dev.yml 分别覆盖了 Unix 与 Windows 平台Windows 版本单独维护正是为了处理平台差异例如 docs/source/contributing/python_style.md 中提到的 Windows 上 pre-commit 钩子对 YAML 文件的空白改动问题在 feature 分支上开发功能git checkout my-feature分支已存在时无需-b标志提交前运行 pre-commit 检查pip install pre-commit pre-commit run --all # 手动运行全部检查 pre-commit install # 安装钩子让每次 commit 前自动运行暂存并提交git add modified_files后执行git commit记录本地改动同步上游并推送提交后建议与主仓库同步避免分叉git fetch upstream git rebase upstream/main git push -u origin my-feature若是首次贡献部分 CI 任务的启动需要维护者批准发起 PR进入你 fork 后的仓库网页点击 Pull request 按钮把改动提交给维护者审查。PR 就绪后建议对照 docs/source/contributing/pr_checklist.md 逐项自检。三、代码贡献礼仪让协作更顺畅的约定指南在pr_etiquette一节中专门规定了代码贡献的行为准则这些约定直接决定了 PR 能否被高效地审查与合入尽早打开 Draft PR开始处理一个 issue 时在完成第一次提交后就立即以Draft草稿状态打开 PR详见 PR 教程以便尽早获得实现细节或 API/功能层面的反馈同时避免重复劳动新功能先提案提交新功能 PR 之前先通过 issue 或 Discussion 与维护者讨论提案。根据提案内容维护者可能会将你引导到其他仓库例如pymc-experimental或pymc-examplesissue 认领规则任何没有对应开放 PR 的 issue 都可认领。反之一个开放的 PR 就是认领该 issue 的方式——请不要在 issue 中做出不切实际的承诺PR 的最近活跃判定若 PR 长时间没有动静可能会被关闭或由他人接手。长时间没有硬性标准通常一个无阻塞的正常 PR 每几天会有一次活动最终由核心开发者根据贡献者、改动性质与上下文因素综合判断中断时请留言如果你被耽搁或需要暂停请在 PR 中留言说明无法推进到可合入状态。核心开发者会根据改动性质紧急 Bug 修复 vs. 新功能决定是否重新指派。代码类贡献的具体方式是参与开放 issue 的讨论或提交解决方案文档类贡献则可以从带有docs标签的开放 issue 入手。四、提交 PR 前的检查清单docs/source/contributing/pr_checklist.md 是合入前的体检表逐项对照可以显著提高 PR 被接受的概率关联 issue若 PR 解决某个 issue应在 PR 标题中描述该问题并在 PR描述中提及 issue 编号从而自动生成指向原 issue 的链接。不要把 issue 编号写进标题——标题中的编号不会生成链接且读者无法凭编号判断含义docstring 规范所有公共方法必须有信息充分的 docstring并在合适时给出示例用法docstring 遵循 numpydoc 风格使用 Draft PR打开 PR 时在下拉菜单中选择 Create draft pull request 以标识工作仍在进行中文档与高覆盖率测试增强功能enhancement要获得接受配套的文档与高覆盖率测试是必要条件补充示例 notebook添加新功能时考虑在pymc-examples仓库中新增一个示例 notebook并先在示例仓库打开一个提案 issue 讨论 notebook 的具体范围回归检查运行pymc-examples中会受到改动影响的分析示例这不仅可能暴露单元测试发现不了的 Bug也能展示你的贡献对最终用户的改进无 pre-commit 报错参考 docs/source/contributing/python_style.md 与 docs/source/contributing/jupyter_style.md 安装并运行全部测试通过所有测试需从零重建后全部通过参见 docs/source/contributing/running_the_test_suite.md。五、代码质量保障pre-commit 与 Python 风格指南docs/source/contributing/python_style.md 说明了如何利用 pre-commit 在本地复现 CI 中的代码质量检查在虚拟环境中安装pip install pre-commit启用钩子pre-commit install。启用后每次git commit都会按仓库根目录的.pre-commit-config.yaml定义运行检查任一钩子失败即阻断提交。你需要修复问题必要时、重新git add再重新 commit。其他常用操作包括跳过全部检查git commit -m wip lol --no-verify跳过单个钩子Linux 示例SKIPruff git commit -m descriptive message手动运行全部钩子pre-commit run --all-files对指定文件运行pre-commit run --files file_1 file_2 ... file_n。常见问题排查pre-commit 只检查已暂存文件若既有 staged 又有 unstaged 改动钩子只作用于 staged 部分若反复报同样的格式化问题先检查是否有未暂存的改动Windows 上 environment YAML 的空白改动pre-commit 钩子的已知 Bug 可能改动部分环境 YAML 文件上游修复前应忽略这些改动。要完成提交可先pre-commit uninstall停用自动钩子确保手动运行pre-commit run --all后再提交mypy 步骤失败仓库通过 mypy 持续改进类型安全但目前仍有大量文件存在未解决的类型问题因此允许部分文件在 mypy 检查中失败。若 mypy 钩子报错可能是你的改动引入了类型问题应修复也可能是修复了类型问题值得庆祝。无论哪种情况都要仔细阅读 mypy 钩子的日志输出其中包含处理指引。也可以手动运行python scripts/run_mypy.py [--verbose]复现检查——仓库中保存了该脚本 scripts/run_mypy.py。Jupyter 笔记本的风格要求文档与示例中的 notebook 还需遵循 docs/source/contributing/jupyter_style.md 的约定要点包括首个单元格需包含 MyST 目标(notebook_name)、一级标题与 post 指令含日期、tags、category、authormarkdown 必须是合法 MyST且绝不使用 url 链接引用其他 notebook 或文档而应使用{ref}交叉引用以保证版本化文档中的自引用不失效变量命名要语义化并标注维度采样结果统一用idata命名 InferenceData 变量notebook 末尾需要## Authors章节与## Watermark章节输出 Python 与依赖版本watermark库已包含在requirements-dev.txt中最后一个单元格是固定的页脚 include 指令。pre-commit 同样对这些 notebook 运行检查可用pre-commit run --files notebook1.ipynb notebook2.ipynb手动验证。六、运行测试套件docs/source/contributing/running_the_test_suite.md 说明 PyMC 的测试基于 pytest。首先安装测试依赖pip install -r requirements-dev.txt重要提醒完整测试套件需要运行数小时因此建议只运行与你改动相关的具体测试。常用测试命令运行单个测试文件pytest -v tests/model/test_core.py-v--verbose会打印当前正在运行的测试用例名称按名称过滤用例用-k匹配模式例如运行test_core.py中名称含 coord 的全部用例pytest -v tests/model/test_core.py -k coord生成覆盖率报告pytest -v --covpymc --cov-report term-missing tests/name of test.py--covpymc统计pymc包的覆盖率--cov-report term-missing打印被测试代码访问到的行号。由于只跑了局部测试覆盖率数字会很低但你可以借此关注自己改动的具体代码行是否被覆盖。当你对改动有足够信心后即可推送并打开 PRGitHub Actions 流水线会运行完整测试套件若有失败可回到本地复现并修复。仓库的测试代码按模块组织在 tests/ 目录下与pymc/包结构一一对应例如 tests/model/test_core.py 对应 pymc/model/core.py 的核心模型逻辑。七、本地构建文档docs/source/contributing/build_docs.md 给出了文档构建流程。注意文档构建不支持 WindowsWindows 用户应在 Docker 容器内构建。首先安装文档依赖在仓库根目录执行conda env create -f conda-envs/environment-docs.yml pip install -e .仓库根目录的 Makefile 封装了构建流程make html使用 sphinx-build 构建文档make clean删除缓存与中间文件仅在重构内容或编辑 toctree 时必要只改单页时可跳过以加快构建。若页面显示异常再依次执行make clean与make html排查make rtd链式执行make clean并附加额外选项与环境变量尽量模拟 readthedocs 构建。注意它不会像真正的 readthedocs 那样在干净环境中重装依赖但会执行core_notebooks文件夹内的全部 notebook默认不执行这会把构建时间延长数分钟6 个 notebook 各需约 20 秒到 5 分钟make view使用 Python 的webbrowser模块在浏览器中打开生成的静态站点无需启动服务器即可预览。八、开发环境的多重选择Docker 与 Gitpod使用 Docker 隔离开发环境docs/source/contributing/docker_container.md 说明仓库提供了 Dockerfile用于隔离构建问题与支持本地开发。安装 Docker、克隆仓库后通过脚本 scripts/docker_container.sh 构建镜像并启动容器cd pymc bash scripts/docker_container.sh build # 构建 pymc 镜像 bash scripts/docker_container.sh bash # 以 bash 进入容器 bash scripts/docker_container.sh jupyter # 以 jupyter notebook端口 8888进入容器仓库中的 scripts/Dockerfile 与 scripts/dev.Dockerfile 共同支撑了该构建流程。使用 Gitpod 零配置开发docs/source/contributing/using_gitpod.md 介绍了浏览器端开发环境 Gitpod 的优势绕开本地机器配置问题、省时、省磁盘空间。工作流如下先 fork 主仓库创建 Gitpod 账户并通过 GitHub 登录授权在 Gitpod 的集成设置中为 GitHub 授予user:email、public_repo、repo、workflow权限创建 New Workspace选择 fork 后的仓库若列表中没有可在 Context URL 粘贴https://github.com/yourusername/pymc后创建。Gitpod 会拉取容器并构建环境约需数分钟环境就绪后终端会出现类似(base) gitpodreshamas-pymc-0ygu5rf74md:/workspace/pymc$的提示符。该环境使用 micromamba 引导完整的 conda 环境安装过程约需 510 分钟用git remote -v核对远程仓库origin指向你的 forkupstream指向官方仓库用pip list | grep pymc与python3 --version确认 pymc 与 Python 版本同步仓库git checkout main再git pull upstream main --tags拉取代码与版本标签最后pip install -e .更新可编辑安装并用python -c import pymc; print(pymc.__version__)验证版本。开始工作前记得创建 feature 分支git checkout -b feature-branch并按git add→git commit→git push origin feature-branch的流程操作。Gitpod 免费计划每月提供 500 额度约 50 小时标准工作区需要注意其工作区生命周期策略默认在无操作 30 分钟后停止最长可调至 24 小时工作区 14 天后删除但固定pin的工作区不会被自动删除。九、深入核心开发实现新分布与开发者指南对希望深度参与核心开发的贡献者仓库还提供了两份进阶文档。实现一个新的 RandomVariable 分布docs/source/contributing/implementing_distribution.md 面向希望向库中新增分布Distribution的开发者给出了五步清单创建新的RandomVariableOp实现对应的Distribution类为新RandomVariable添加测试为logp/logcdf/icdf/support_point方法添加测试编写新Distribution的文档。其核心思想是PyMC 的Distribution构建在 PyTensor 的RandomVariable之上并实现logp、logcdf、icdf、support_point方法以及初始化与校验辅助逻辑最引人注目的是shape/dims/observed关键字、替代参数化方式与默认transform。创建新的RandomVariable前先确认该分布是否已存在于 NumPy 库——若是应先加入 PyTensor 库再导入 PyMC同时并非所有新分布都需要新的RandomVariable例如OrderedLogistic与OrderedProbit只是Categorical分布的特殊参数化。文档提供了完整的RandomVariable实现骨架包括signatureNumPy 风格签名标明各输入输出的核心维度、dtype离散变量标准为int64连续变量为floatX、_print_name文本与 LaTeX 表示以及rng_fn接收 NumPyRandomState、分布参数与size返回样本的采样实现。普通用户不需要接触这些复杂性直接使用pm.CustomDist之类的辅助方法即可。PyMC 开发者指南docs/source/contributing/developer_guide.md 从实现层面解释了 PyMC 的设计概率分布类继承自Continuous或Discrete二者又继承定义高层 API 的Distribution。在pm.Model()上下文内调用pm.Normal(z, 0, 5)会返回一个 PyTensorTensorVariable其背后经由Distribution.distAPI 调用对应的RandomVariableOp模型上下文相当于一台磁带机记录 named_vars、free_RVs、observed_RVs、deterministics、potentials、missing_values 等信息。文档还深入讲解了logp的求值机制、pm.Model编译的logp/dlogp系列函数、MCMC 中CompoundStepMetropolis-within-Gibbs 概念的实现见 pymc/step_methods/compound.py、NUTS 动态 HMC、变分推断pymc/variational/inference.py 与 pymc/variational/opvi.py以及前向采样等内部机制并坦诚讨论了实现中踩过的坑shape 处理、numpy 随机方法、Python 实现的采样器带来的性能开销等。十、版本发布流程docs/source/contributing/release_checklist.md 描述了维护者侧的发布工作流通过版本专属的 milestone跟踪所有相关 issue 与 PR确认没有不应随版本发布的重大已知 Bug提交一个 PR提升版本号__init__.py并编辑RELEASE-NOTES.md在顶部新建 vNext 小节、把标题改为发布版本与日期、按以往格式添加一行致谢发布经理。PR 名称不要与版本同名并像普通贡献者一样推送到自己的 fork合并 PR 后确认 master 分支的 CI 流水线全部通过以v1.2.3格式创建 Tag 并配有人性化标题的 Release此后 GitHub Actionrelease-pipeline会自动构建并把新版本发布到 PyPI。排错提示若需撤销发布可在 PyPI 与 GitHub 上手动删除但PyPI 不接受相同版本号的再次发布release-pipeline的test-install-job可能因 PyPI 索引更新不及时而失败。发布后还需把 Zenodo 生成的版本专属 DOI 徽章复制进发布说明、关闭并重命名已发布 milestone 并新建 vNext milestone、关注 conda-forge 的pymc-feedstock自动更新 PR可能需手动干预、用新版本重跑示例 notebook并确认文档站点稳定版已指向新版本。十一、机构贡献成为 Institutional Partner 或 Sponsor除了个人贡献PyMC 也接受机构层面的支持。指南明确指出机构可以通过两种方式参与成为机构合作伙伴Institutional Partners成为赞助商Sponsors。这两类身份的详细说明与资金相关条款记录在仓库根目录的 GOVERNANCE.md 中其Institutional Partners and Funding与Sponsors小节有合作意向的机构可通过指南中给出的邮箱pymc.devsgmail.com联系项目组。此外docs/logos/sponsors/目录下存放了 numfocus、odsc、pymc-labs 等现有赞助方的标识素材可见机构赞助已是 PyMC 生态的现实组成部分。十二、贡献者文档导航总览贡献指南的索引页通过隐藏 toctree 把整套贡献文档组织为四个层次方便按需查阅以下均以仓库根目录为基准层次文档适用场景Tutorialsdocs/source/contributing/pr_tutorial.md第一次提交 PR 的完整步骤How-to guidesdocs/source/contributing/build_docs.md、docs/source/contributing/docker_container.md、docs/source/contributing/running_the_test_suite.md、docs/source/contributing/review_pr_pymc_examples.md、docs/source/contributing/using_gitpod.md、docs/source/contributing/implementing_distribution.md构建文档、容器开发、跑测试、审查示例 PR、Gitpod 环境、实现新分布Reference contentdocs/source/contributing/python_style.md、docs/source/contributing/jupyter_style.md、docs/source/contributing/pr_checklist.md、docs/source/contributing/release_checklist.md风格规范、检查清单、发布流程In depth explanationsdocs/source/contributing/versioning_schemes_explanation.md版本管理方案背后的原理仓库根目录的 CONTRIBUTING.md 则是一份精简入口将外部访问者快速引导至上述贡献文档站点。整套体系从想贡献的动机出发一路覆盖到合入、发布与机构合作构成了一条完整的开源参与闭环——无论你是第一次提交 PR 的新手还是准备实现新分布的资深开发者都可以在这套文档与仓库源码中找到对应的路线图。【免费下载链接】pymcBayesian Modeling and Probabilistic Programming in Python项目地址: https://gitcode.com/GitHub_Trending/py/pymc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PyMC 开源贡献完整指南：从个人提交到机构合作的全流程实践
PyMC 开源贡献完整指南从个人提交到机构合作的全流程实践【免费下载链接】pymcBayesian Modeling and Probabilistic Programming in Python项目地址: https://gitcode.com/GitHub_Trending/py/pymcPyMC 是一个以 Python 编写的开源贝叶斯统计建模与概率编程框架其官方贡献指南docs/source/contributing/index.md明确了这是一个集体努力的项目任何人都可以以自己擅长的方式参与建设。本文以该指南为核心骨架完整梳理 PyMC 的贡献方式、Pull Request 全流程、代码礼仪、质量检查、测试运行、文档构建、开发环境搭建以及机构合作路径并结合仓库内真实源码与配置逐一佐证帮助你从想贡献到会贡献走通每一步。一、贡献方式的总体图景PyMC 是集体努力的开源项目PyMC 的贡献指南开宗明义地指出PyMC 是一个开源、集体努力的项目PyMC is an open source, collective effort有非常多的方式可以让它变得更好且所有方式都受到欢迎。编码coding和文档documentation是最常见的贡献类型但绝非全部——指南明确列出以下同样重要的非代码贡献方向报告 Bug 或提出改进建议通过 GitHub 的 issue 新建入口提交问题报告或改进提案在社区论坛回答问题帮助其他用户在 Discourse 论坛上解答疑问教学与传播最佳实践通过写博客或做演讲推广 PyMC 的正确用法参与 PyMCon 的策划PyMCon 是 PyMC 社区主办的科学会议推广与外联包括联系潜在的赞助公司、向可能在工作与学术研究中用得上 PyMC 的人介绍它以及确保使用 PyMC 的学者在论文中正确引用协助筹款工作为 PyMCon 的视频添加时间戳。指南特别提示如果还不确定自己能贡献什么、如何开始可以通过 Discourse 论坛联系团队也可以订阅office-hours标签参与定期举办的office hours获得面向贡献者的专门支持。对于刚接触开源的新手指南还推荐参考 sprint 材料——即使不参加 sprint 活动这套材料也是目前可用的最详细贡献入门指导。二、通过 Pull Request 贡献完整的分步教程代码与文档贡献都需要通过 GitHub 向 pymc-devs 组织下的仓库提交 Pull RequestPR。仓库中保存了完整的步骤化教程 docs/source/contributing/pr_tutorial.md推荐的工作流是fork 主仓库 → 克隆到本地 → 在 feature 分支上开发。其完整步骤如下先阅读代码贡献礼仪见下文第三节Fork 主仓库点击主仓库页面右上角的 Fork 按钮在你的 GitHub 账户下生成一份代码副本克隆并配置远程仓库git clone gitgithub.com:your GitHub handle/pymc.git cd pymc git remote add upstream gitgithub.com:pymc-devs/pymc.git其中upstream指向 pymc-devs 官方主仓库origin指向你自己的 fork创建 feature 分支git checkout -b my-feature注意始终使用 feature 分支。在任何仓库中都不应养成直接在main分支上工作的习惯搭建开发环境项目运行依赖在requirements.txt开发依赖在requirements-dev.txt。指南推荐使用 miniconda 通过 conda 环境文件一键创建Linux/MacOSconda env create -f conda-envs/environment-dev.ymlWindows 与 WindowsGit Bashconda env create -f conda-envs/windows-environment-dev.yml创建完成后激活环境并以可编辑模式安装本地包conda activate pymc-dev pip install -e .另一种等价方式是在虚拟环境中执行pip install -e .后再pip install -r requirements-dev.txt。从仓库结构看conda-envs/environment-dev.yml 与 conda-envs/windows-environment-dev.yml 分别覆盖了 Unix 与 Windows 平台Windows 版本单独维护正是为了处理平台差异例如 docs/source/contributing/python_style.md 中提到的 Windows 上 pre-commit 钩子对 YAML 文件的空白改动问题在 feature 分支上开发功能git checkout my-feature分支已存在时无需-b标志提交前运行 pre-commit 检查pip install pre-commit pre-commit run --all # 手动运行全部检查 pre-commit install # 安装钩子让每次 commit 前自动运行暂存并提交git add modified_files后执行git commit记录本地改动同步上游并推送提交后建议与主仓库同步避免分叉git fetch upstream git rebase upstream/main git push -u origin my-feature若是首次贡献部分 CI 任务的启动需要维护者批准发起 PR进入你 fork 后的仓库网页点击 Pull request 按钮把改动提交给维护者审查。PR 就绪后建议对照 docs/source/contributing/pr_checklist.md 逐项自检。三、代码贡献礼仪让协作更顺畅的约定指南在pr_etiquette一节中专门规定了代码贡献的行为准则这些约定直接决定了 PR 能否被高效地审查与合入尽早打开 Draft PR开始处理一个 issue 时在完成第一次提交后就立即以Draft草稿状态打开 PR详见 PR 教程以便尽早获得实现细节或 API/功能层面的反馈同时避免重复劳动新功能先提案提交新功能 PR 之前先通过 issue 或 Discussion 与维护者讨论提案。根据提案内容维护者可能会将你引导到其他仓库例如pymc-experimental或pymc-examplesissue 认领规则任何没有对应开放 PR 的 issue 都可认领。反之一个开放的 PR 就是认领该 issue 的方式——请不要在 issue 中做出不切实际的承诺PR 的最近活跃判定若 PR 长时间没有动静可能会被关闭或由他人接手。长时间没有硬性标准通常一个无阻塞的正常 PR 每几天会有一次活动最终由核心开发者根据贡献者、改动性质与上下文因素综合判断中断时请留言如果你被耽搁或需要暂停请在 PR 中留言说明无法推进到可合入状态。核心开发者会根据改动性质紧急 Bug 修复 vs. 新功能决定是否重新指派。代码类贡献的具体方式是参与开放 issue 的讨论或提交解决方案文档类贡献则可以从带有docs标签的开放 issue 入手。四、提交 PR 前的检查清单docs/source/contributing/pr_checklist.md 是合入前的体检表逐项对照可以显著提高 PR 被接受的概率关联 issue若 PR 解决某个 issue应在 PR 标题中描述该问题并在 PR描述中提及 issue 编号从而自动生成指向原 issue 的链接。不要把 issue 编号写进标题——标题中的编号不会生成链接且读者无法凭编号判断含义docstring 规范所有公共方法必须有信息充分的 docstring并在合适时给出示例用法docstring 遵循 numpydoc 风格使用 Draft PR打开 PR 时在下拉菜单中选择 Create draft pull request 以标识工作仍在进行中文档与高覆盖率测试增强功能enhancement要获得接受配套的文档与高覆盖率测试是必要条件补充示例 notebook添加新功能时考虑在pymc-examples仓库中新增一个示例 notebook并先在示例仓库打开一个提案 issue 讨论 notebook 的具体范围回归检查运行pymc-examples中会受到改动影响的分析示例这不仅可能暴露单元测试发现不了的 Bug也能展示你的贡献对最终用户的改进无 pre-commit 报错参考 docs/source/contributing/python_style.md 与 docs/source/contributing/jupyter_style.md 安装并运行全部测试通过所有测试需从零重建后全部通过参见 docs/source/contributing/running_the_test_suite.md。五、代码质量保障pre-commit 与 Python 风格指南docs/source/contributing/python_style.md 说明了如何利用 pre-commit 在本地复现 CI 中的代码质量检查在虚拟环境中安装pip install pre-commit启用钩子pre-commit install。启用后每次git commit都会按仓库根目录的.pre-commit-config.yaml定义运行检查任一钩子失败即阻断提交。你需要修复问题必要时、重新git add再重新 commit。其他常用操作包括跳过全部检查git commit -m wip lol --no-verify跳过单个钩子Linux 示例SKIPruff git commit -m descriptive message手动运行全部钩子pre-commit run --all-files对指定文件运行pre-commit run --files file_1 file_2 ... file_n。常见问题排查pre-commit 只检查已暂存文件若既有 staged 又有 unstaged 改动钩子只作用于 staged 部分若反复报同样的格式化问题先检查是否有未暂存的改动Windows 上 environment YAML 的空白改动pre-commit 钩子的已知 Bug 可能改动部分环境 YAML 文件上游修复前应忽略这些改动。要完成提交可先pre-commit uninstall停用自动钩子确保手动运行pre-commit run --all后再提交mypy 步骤失败仓库通过 mypy 持续改进类型安全但目前仍有大量文件存在未解决的类型问题因此允许部分文件在 mypy 检查中失败。若 mypy 钩子报错可能是你的改动引入了类型问题应修复也可能是修复了类型问题值得庆祝。无论哪种情况都要仔细阅读 mypy 钩子的日志输出其中包含处理指引。也可以手动运行python scripts/run_mypy.py [--verbose]复现检查——仓库中保存了该脚本 scripts/run_mypy.py。Jupyter 笔记本的风格要求文档与示例中的 notebook 还需遵循 docs/source/contributing/jupyter_style.md 的约定要点包括首个单元格需包含 MyST 目标(notebook_name)、一级标题与 post 指令含日期、tags、category、authormarkdown 必须是合法 MyST且绝不使用 url 链接引用其他 notebook 或文档而应使用{ref}交叉引用以保证版本化文档中的自引用不失效变量命名要语义化并标注维度采样结果统一用idata命名 InferenceData 变量notebook 末尾需要## Authors章节与## Watermark章节输出 Python 与依赖版本watermark库已包含在requirements-dev.txt中最后一个单元格是固定的页脚 include 指令。pre-commit 同样对这些 notebook 运行检查可用pre-commit run --files notebook1.ipynb notebook2.ipynb手动验证。六、运行测试套件docs/source/contributing/running_the_test_suite.md 说明 PyMC 的测试基于 pytest。首先安装测试依赖pip install -r requirements-dev.txt重要提醒完整测试套件需要运行数小时因此建议只运行与你改动相关的具体测试。常用测试命令运行单个测试文件pytest -v tests/model/test_core.py-v--verbose会打印当前正在运行的测试用例名称按名称过滤用例用-k匹配模式例如运行test_core.py中名称含 coord 的全部用例pytest -v tests/model/test_core.py -k coord生成覆盖率报告pytest -v --covpymc --cov-report term-missing tests/name of test.py--covpymc统计pymc包的覆盖率--cov-report term-missing打印被测试代码访问到的行号。由于只跑了局部测试覆盖率数字会很低但你可以借此关注自己改动的具体代码行是否被覆盖。当你对改动有足够信心后即可推送并打开 PRGitHub Actions 流水线会运行完整测试套件若有失败可回到本地复现并修复。仓库的测试代码按模块组织在 tests/ 目录下与pymc/包结构一一对应例如 tests/model/test_core.py 对应 pymc/model/core.py 的核心模型逻辑。七、本地构建文档docs/source/contributing/build_docs.md 给出了文档构建流程。注意文档构建不支持 WindowsWindows 用户应在 Docker 容器内构建。首先安装文档依赖在仓库根目录执行conda env create -f conda-envs/environment-docs.yml pip install -e .仓库根目录的 Makefile 封装了构建流程make html使用 sphinx-build 构建文档make clean删除缓存与中间文件仅在重构内容或编辑 toctree 时必要只改单页时可跳过以加快构建。若页面显示异常再依次执行make clean与make html排查make rtd链式执行make clean并附加额外选项与环境变量尽量模拟 readthedocs 构建。注意它不会像真正的 readthedocs 那样在干净环境中重装依赖但会执行core_notebooks文件夹内的全部 notebook默认不执行这会把构建时间延长数分钟6 个 notebook 各需约 20 秒到 5 分钟make view使用 Python 的webbrowser模块在浏览器中打开生成的静态站点无需启动服务器即可预览。八、开发环境的多重选择Docker 与 Gitpod使用 Docker 隔离开发环境docs/source/contributing/docker_container.md 说明仓库提供了 Dockerfile用于隔离构建问题与支持本地开发。安装 Docker、克隆仓库后通过脚本 scripts/docker_container.sh 构建镜像并启动容器cd pymc bash scripts/docker_container.sh build # 构建 pymc 镜像 bash scripts/docker_container.sh bash # 以 bash 进入容器 bash scripts/docker_container.sh jupyter # 以 jupyter notebook端口 8888进入容器仓库中的 scripts/Dockerfile 与 scripts/dev.Dockerfile 共同支撑了该构建流程。使用 Gitpod 零配置开发docs/source/contributing/using_gitpod.md 介绍了浏览器端开发环境 Gitpod 的优势绕开本地机器配置问题、省时、省磁盘空间。工作流如下先 fork 主仓库创建 Gitpod 账户并通过 GitHub 登录授权在 Gitpod 的集成设置中为 GitHub 授予user:email、public_repo、repo、workflow权限创建 New Workspace选择 fork 后的仓库若列表中没有可在 Context URL 粘贴https://github.com/yourusername/pymc后创建。Gitpod 会拉取容器并构建环境约需数分钟环境就绪后终端会出现类似(base) gitpodreshamas-pymc-0ygu5rf74md:/workspace/pymc$的提示符。该环境使用 micromamba 引导完整的 conda 环境安装过程约需 510 分钟用git remote -v核对远程仓库origin指向你的 forkupstream指向官方仓库用pip list | grep pymc与python3 --version确认 pymc 与 Python 版本同步仓库git checkout main再git pull upstream main --tags拉取代码与版本标签最后pip install -e .更新可编辑安装并用python -c import pymc; print(pymc.__version__)验证版本。开始工作前记得创建 feature 分支git checkout -b feature-branch并按git add→git commit→git push origin feature-branch的流程操作。Gitpod 免费计划每月提供 500 额度约 50 小时标准工作区需要注意其工作区生命周期策略默认在无操作 30 分钟后停止最长可调至 24 小时工作区 14 天后删除但固定pin的工作区不会被自动删除。九、深入核心开发实现新分布与开发者指南对希望深度参与核心开发的贡献者仓库还提供了两份进阶文档。实现一个新的 RandomVariable 分布docs/source/contributing/implementing_distribution.md 面向希望向库中新增分布Distribution的开发者给出了五步清单创建新的RandomVariableOp实现对应的Distribution类为新RandomVariable添加测试为logp/logcdf/icdf/support_point方法添加测试编写新Distribution的文档。其核心思想是PyMC 的Distribution构建在 PyTensor 的RandomVariable之上并实现logp、logcdf、icdf、support_point方法以及初始化与校验辅助逻辑最引人注目的是shape/dims/observed关键字、替代参数化方式与默认transform。创建新的RandomVariable前先确认该分布是否已存在于 NumPy 库——若是应先加入 PyTensor 库再导入 PyMC同时并非所有新分布都需要新的RandomVariable例如OrderedLogistic与OrderedProbit只是Categorical分布的特殊参数化。文档提供了完整的RandomVariable实现骨架包括signatureNumPy 风格签名标明各输入输出的核心维度、dtype离散变量标准为int64连续变量为floatX、_print_name文本与 LaTeX 表示以及rng_fn接收 NumPyRandomState、分布参数与size返回样本的采样实现。普通用户不需要接触这些复杂性直接使用pm.CustomDist之类的辅助方法即可。PyMC 开发者指南docs/source/contributing/developer_guide.md 从实现层面解释了 PyMC 的设计概率分布类继承自Continuous或Discrete二者又继承定义高层 API 的Distribution。在pm.Model()上下文内调用pm.Normal(z, 0, 5)会返回一个 PyTensorTensorVariable其背后经由Distribution.distAPI 调用对应的RandomVariableOp模型上下文相当于一台磁带机记录 named_vars、free_RVs、observed_RVs、deterministics、potentials、missing_values 等信息。文档还深入讲解了logp的求值机制、pm.Model编译的logp/dlogp系列函数、MCMC 中CompoundStepMetropolis-within-Gibbs 概念的实现见 pymc/step_methods/compound.py、NUTS 动态 HMC、变分推断pymc/variational/inference.py 与 pymc/variational/opvi.py以及前向采样等内部机制并坦诚讨论了实现中踩过的坑shape 处理、numpy 随机方法、Python 实现的采样器带来的性能开销等。十、版本发布流程docs/source/contributing/release_checklist.md 描述了维护者侧的发布工作流通过版本专属的 milestone跟踪所有相关 issue 与 PR确认没有不应随版本发布的重大已知 Bug提交一个 PR提升版本号__init__.py并编辑RELEASE-NOTES.md在顶部新建 vNext 小节、把标题改为发布版本与日期、按以往格式添加一行致谢发布经理。PR 名称不要与版本同名并像普通贡献者一样推送到自己的 fork合并 PR 后确认 master 分支的 CI 流水线全部通过以v1.2.3格式创建 Tag 并配有人性化标题的 Release此后 GitHub Actionrelease-pipeline会自动构建并把新版本发布到 PyPI。排错提示若需撤销发布可在 PyPI 与 GitHub 上手动删除但PyPI 不接受相同版本号的再次发布release-pipeline的test-install-job可能因 PyPI 索引更新不及时而失败。发布后还需把 Zenodo 生成的版本专属 DOI 徽章复制进发布说明、关闭并重命名已发布 milestone 并新建 vNext milestone、关注 conda-forge 的pymc-feedstock自动更新 PR可能需手动干预、用新版本重跑示例 notebook并确认文档站点稳定版已指向新版本。十一、机构贡献成为 Institutional Partner 或 Sponsor除了个人贡献PyMC 也接受机构层面的支持。指南明确指出机构可以通过两种方式参与成为机构合作伙伴Institutional Partners成为赞助商Sponsors。这两类身份的详细说明与资金相关条款记录在仓库根目录的 GOVERNANCE.md 中其Institutional Partners and Funding与Sponsors小节有合作意向的机构可通过指南中给出的邮箱pymc.devsgmail.com联系项目组。此外docs/logos/sponsors/目录下存放了 numfocus、odsc、pymc-labs 等现有赞助方的标识素材可见机构赞助已是 PyMC 生态的现实组成部分。十二、贡献者文档导航总览贡献指南的索引页通过隐藏 toctree 把整套贡献文档组织为四个层次方便按需查阅以下均以仓库根目录为基准层次文档适用场景Tutorialsdocs/source/contributing/pr_tutorial.md第一次提交 PR 的完整步骤How-to guidesdocs/source/contributing/build_docs.md、docs/source/contributing/docker_container.md、docs/source/contributing/running_the_test_suite.md、docs/source/contributing/review_pr_pymc_examples.md、docs/source/contributing/using_gitpod.md、docs/source/contributing/implementing_distribution.md构建文档、容器开发、跑测试、审查示例 PR、Gitpod 环境、实现新分布Reference contentdocs/source/contributing/python_style.md、docs/source/contributing/jupyter_style.md、docs/source/contributing/pr_checklist.md、docs/source/contributing/release_checklist.md风格规范、检查清单、发布流程In depth explanationsdocs/source/contributing/versioning_schemes_explanation.md版本管理方案背后的原理仓库根目录的 CONTRIBUTING.md 则是一份精简入口将外部访问者快速引导至上述贡献文档站点。整套体系从想贡献的动机出发一路覆盖到合入、发布与机构合作构成了一条完整的开源参与闭环——无论你是第一次提交 PR 的新手还是准备实现新分布的资深开发者都可以在这套文档与仓库源码中找到对应的路线图。【免费下载链接】pymcBayesian Modeling and Probabilistic Programming in Python项目地址: https://gitcode.com/GitHub_Trending/py/pymc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考