Jupyter 开发者指南:从源码安装、提交 PR 到版本发布的完整协作流程

原创2026-09-21 13:23:581,755 阅读
文章标签:开发工具

Jupyter 开发者指南:从源码安装、提交 PR 到版本发布的完整协作流程

本指南以 Jupyter 官方仓库的 Developer Guide(索引页)为核心骨架,系统讲解 Jupyter 生态的开发者协作全流程:如何从源码安装各 Jupyter 项目、如何查找并认领 Issue、如何按规范提交 Pull Request、核心开发者如何合并与 backport,以及从 milestone 管理到 PyPI 发布的完整发布流程。读完本文,你将掌握一套可直接照做的 Jupyter 贡献与发布操作手册,并了解当前仓库(jupyter metapackage)是如何把发布与文档构建落到实处的。

一、开发者指南概览

本仓库的 Developer Guide 位于 docs/source/contributing/dev-contributions/,由四个文件组成,形成"贡献 → 提案 → 发布"的完整闭环:

文档 主题
index.rst 开发者指南入口,说明源码安装方式与文档结构
contrib_guide.md 贡献指南:PR 提交、贡献工作流、backport、Bug 与漏洞报告
jupyter_enhancement_proposals.rst Jupyter 增强提案(JEP)的提交流程
releasing.rst 发布一个 Jupyter 项目的通用模板

无论是新贡献者还是资深开发者,都可以把这份指南作为入手起点。Jupyter 团队欢迎任何形式的帮助——哪怕只是修复一个 issue 所必需的一小段代码,任何人和任何形式的贡献都被鼓励。

二、从源码安装 Jupyter 项目

要开发 Jupyter 系列项目,第一步通常是直接从源码目录安装。绝大多数 Jupyter 包与普通 Python 包无异,在源码目录下执行即可:

pip install .

本仓库本身就是一个典型例子:setup.py 定义了名为 jupyter 的 metapackage(元包),自身不含任何代码(py_modules = []),只通过 install_requires 一次性拉起常用 Jupyter 组件:

install_requires = [
    'notebook',
    'nbconvert',
    'ipykernel',
    'ipywidgets',
    'jupyterlab',
],

即执行 pip install . 会同时安装 Jupyter Notebook、JupyterLab 与 IPython Kernel(详见 long_description.md)。需要注意两点:其一,jupyter 元包仅是为用户便捷而存在,不应作为其他包的依赖;其二,如果只想装其中部分组件,可以单独安装 notebook、jupyterlab、ipython、ipykernel、jupyter-console、nbconvert、ipywidgets 等。

另外要特别说明:Jupyter Notebook 的源码安装需要额外步骤来构建 JavaScript 组件(前端资源无法像纯 Python 包一样直接 pip install),相关内容在 notebook 的贡献者文档的"设置开发环境"一节中有详细说明,动手前务必先读那一节。

三、第一步:找到适合你的 Issue

Jupyter 的代码库分散在 jupyter 组织下的多个仓库中,而不是集中在一个仓库,因此用 GitHub 搜索跨仓库检索 issue 特别有用。文档推荐使用如下查询语句来筛出适合新手/冲刺(sprint)友好型的公开 issue:

is:issue is:open is:sprint-friendly user:jupyter

找到感兴趣的 issue 后,直接按下一节的操作流程开工;如果过程中遇到任何问题,在 issue 页留言即可,核心团队成员会出手相助。需要注意,下文流程本质上是"指南"而非"死规定"——如果做到一半遇到时间紧张或疑问,完全可以先把当前进度(哪怕是半成品)提成 PR,然后在 PR 上提问,你的努力——包括部分或进行中的工作——都会被认可。

四、提交 Pull Request:12 步完整流程

contrib_guide.md 给出了一个可逐步执行的 PR 提交流程,完整步骤如下:

  1. Fork 并克隆:Fork 与 issue 对应的仓库,克隆到本地目录。
  2. 创建分支:cd 进目录后执行 git checkout -b insert-branch-name-here。分支名应体现要解决的问题,例如更新某错误日志文本时,可命名为 update-error-text。
  3. 配置开发环境:参考目标仓库的 README 与文档,完成系统级开发环境配置。
  4. 定位代码位置:确定改动所在的模块或类,并在文件内留下注释,说明你试图解决哪个 issue。
  5. 尽早开 PR:向仓库提交 Pull Request,并在标题前加 [WIP],让核心团队知道你正在积极跟进。PR 标题应简洁准确地描述代码行为(例如 "Updated error message on ExampleException"),PR 描述中务必包含 Closes #issue-number-here(替换为实际 issue 号)。越早开 PR,越早获得方向性反馈,可以避免后期大范围重构。
  6. 运行测试套件:在本地跑测试,确认环境配置正确。具体命令参考目标仓库 README(文档给出的传统方式是命令行执行 nosetests);也可以直接提交 PR,让 CI 系统代为测试并报告结果。
  7. 编写测试用例:找到与被改模块对应的测试文件,添加能描述预期行为的测试。例如,若你改了异常日志文本,可以写测试断言"触发该错误时抛出的异常包含相应字符串"。写测试时至少思考以下几点:
    • 针对该 issue,我能写的最简测试是什么?
    • 代码收到"脏"输入时会发生什么?
    • 代码收到空输入时会发生什么?
    • 代码收到过少输入时会发生什么?
    • 代码收到过多输入时会发生什么?
    • 需要帮助时可以在此前开的 PR 下留言,核心成员会协助。
  8. 实现代码:回到要修改的文件,开始编写 PR 对应的实现代码。
  9. 再次运行测试:确认改动是否让用例通过;若有失败,回头修改代码直到通过。
  10. 提交并推送:全部用例通过后,同时提交测试用例与修改后的模块,推送到 fork 仓库的分支。
  11. 请求评审:准备好被评审后,去掉标题前的 [WIP] 标签。评审人会重点检查三方面:改动附带的文档、测试用例的完备程度、代码效率。评审会给出反馈,你有机会据此修改并重新提交。
  12. 合并:PR 达到入库标准后,由核心团队成员合并进主分支。

五、贡献工作流:14 节点流程全景

下面的流程图(出自原贡献指南,见 contrib_guide.md)用 14 个节点串起了从"开始"到"庆祝并继续"的单向贡献流程,每个节点可前进到下一步,也可能回退到上一步:

Jupyter 贡献代码工作流:14 个步骤的单向流程图,每步有前进与回退箭头,节点为"开始"到"庆祝并继续"

该流程的文字版描述如下:

  1. 开始 → 找到要解决的 issue
  2. 找到要解决的 issue → 定位代码库中的相关模块
  3. 定位相关模块 → 编写简单的测试用例,验证你的修复或增强能正常工作
  4. 编写测试用例 → 在合适位置实现 Bug 修复或增强功能
  5. 实现修复/增强 → 运行测试套件,确认更新后的代码工作正常
  6. 运行测试套件 → 分支:测试通过! 或 测试失败!
  7. 测试失败 → 定位并修复新代码中导致错误的问题;可参考邮件列表或 Zulip 频道求助
  8. 修复问题 → 回到"运行测试套件"
  9. 测试通过! → 向对应仓库提交包含优秀代码的 Pull Request
  10. 提交 PR → 分支:评审人批准并合并 或 评审人要求修改
  11. 评审人要求修改 → 对 PR 应用必要修复或更新
  12. 应用修改 → 回到"提交 PR"
  13. 评审人批准并合并 PR → 庆祝并重复
  14. 庆祝并重复!(流程回到起点,迎接下一个贡献)

六、核心开发者工作流:合并与 backport

提交 PR 之后,核心开发者的评审与合并过程遵循一套通用流程(各仓库细节略有差异),文档以 Jupyter Notebook 4.x 为例展开。

一般而言,PR 默认合入 master 分支,除非它只影响 backport 分支。如果一个 PR 同时影响 master 且需要 backport,标准流程为:

  1. 为 PR 标记下一个 backport 版本(例如 4.3)的 milestone;
  2. 合并进 master;
  3. backport 到 4.x 分支;
  4. 推送更新后的 4.x 分支。

backport 有多种实现方式,Jupyter 社区维护了一个脚本来自动化常见流程(参考 IPython 仓库的 tools/backport_pr.py),其核心动作是:

  1. 下载补丁(例如 jupyter/notebook 的 PR #1645 对应补丁);
  2. 检出 4.x 分支;
  3. 应用补丁;
  4. 提交。

这个脚本至少对简单场景是有效的。实际调用示例:

python /path/to/ipython-repo/tools/backport_pr.py jupyter/notebook 4.x 1645

七、提交 Bug 报告:让问题可复现、可定位

使用 Notebook 时遇到异常行为,欢迎到 GitHub 提 issue。为了让开发者和用户都能高效地在 issue 列表中导航,提交前请依次完成:

  1. 先搜索:在 StackOverflow 和已有 GitHub issues 中检索,确认该问题尚未被报告过;若已有相关 issue,可在其上补充你认为有价值的输入。
  2. 准备最小复现片段:写一段小而自包含的代码,让其他人能据此复现问题。
  3. 准备环境信息:提供 Python 版本、Jupyter 版本、操作系统、浏览器等信息,便于调试。可用 pip list 或 conda list 配合 grep 快速筛出与问题相关的库版本。
  4. 准备预期行为:写一个能描述代码预期行为的简单测试,或一段对预期行为的文字描述。
  5. 解释差异:说明为什么当前行为不符合预期、期望的行为应该是什么。

八、报告安全漏洞

如果你认为在某个 Jupyter 项目中发现了安全漏洞,请将其报告至 security@ipython.org;若希望加密发送安全报告,可以使用该项目公布的 PGP 公钥进行加密。安全漏洞报告应独立于普通 issue 处理,以保证修复窗口期的信息控制。

九、Jupyter Enhancement Proposals(JEP)提交流程

在使用 Notebook 过程中发现值得改进的方向或新功能需求时,可以提交增强提案。提交流程如下:

  1. 界定范围:判断增强只影响代码库的哪一部分、实现是否足够简单。小范围的增强应作为 issue 提交到项目仓库;大范围的增强则应提交到官方的 Jupyter Enhancement Proposals 仓库。
  2. 写问题描述:简要说明你的增强要解决的问题。
  3. 写方案描述:简要说明你提议的增强本身。
  4. 写实现草案:如果第 1 步判定为大规模增强,则需要详细写出潜在的实现方案。
  5. 列出利弊:给出实现该增强的简要优点与缺点清单。
  6. 识别相关人员:找出可能对实现该增强感兴趣的人。
  7. 提交:根据范围,选择提交为仓库 issue,或提交为正式的 Jupyter Enhancement Proposal(JEP)。

十、发布一个 Jupyter 项目:从 Milestone 到 PyPI

releasing.rst 提供了一套"小而美"项目的发布模板,大项目也适用,只是可能多出一些步骤。Jupyter 生态由若干小项目加少量大项目构成,以下流程是标准发布路径。

10.1 Milestone:发布的前置准备

多数 Jupyter 项目用 GitHub 的 milestone 系统来为 issue 和 PR 归类到具体版本。每个发布都应有对应的 milestone,准备发布的第一步是确保每个 issue 和 PR 都有正确的 milestone:

  1. 检查标记为当前 milestone 的所有未关闭 issue 和 PR:若有遗留,需在本次发布前解决,或把它们"提升"(bump)到下一个 milestone。把 issue 提升是常见做法——它们通常被乐观地标上最早可行的版本,但发布时刻未必都完成。
  2. 检查已关闭的 issue 和 PR,使用 milestone 筛选器 "Issues with no milestone":理论上不应存在任何没有 milestone 的已关闭 issue 或 PR;若发现,按情况补标当前 milestone 或标为 "no action"。

当当前 milestone 下零个未关闭 issue/PR 时,发布条件即告成熟。

10.2 编写 Release Notes

处理完 issue 和 PR 后,开始编写发布说明:

  • 小项目通常在 docs 目录下有一个 changelog.rst,在其中为本次新版本新增一节;
  • 翻阅当前 milestone 下已合并的 PR(这正是使用 milestone 的原因),为本次发布的变更亮点写简短摘要;
  • 一般应在 release notes 中链接到对应 milestone 以提供更多细节;
  • 用独立 PR 提交这些 notes,并建议请 @willingc 审阅该 PR,同时务必为该 PR 标记发布对应的 milestone。

10.3 执行发布:命令级操作手册

changelog 合并后即可构建并发布。假设已用 shell 变量声明版本号:

export V=5.1.2

第一步,确保 master 是干净检出、无多余文件:

git pull
git clean -xfd

第二步,更新版本号:通常在 <pkg>/_version.py 或类似文件中修改版本,并提交:

git commit -am "release $V"

建议此时跑一遍测试,确认改版本号没有引起任何混乱。

第三步,构建发行包:

python setup.py sdist --formats=gztar
python setup.py bdist_wheel

第四步,打标签:

git tag -am "release $V" $V

第五步,发布到 GitHub 与 PyPI(PyPI 使用 twine 上传):

twine upload dist/*
git push origin
git push origin --tags

发布完成!第六步,回到开发版本:再次编辑 <pkg>/_version.py(或类似文件),把版本号提升到下一个 .dev 版本并提交推送:

git commit -am "back to dev"
git push origin

注意:上述 push 假设 origin 指向主 jupyter/ipython 仓库;按你的 git 使用习惯,远程名可能是 upstream 或其他。

10.4 本仓库的发布实践:tbump 自动化

回到当前仓库,jupyter metapackage 自己的发布则采用了更自动化的 tbump 方案(见 README.md 的 "Releasing the jupyter metapackage" 一节,该包发布频率很低):拥有推送权限的开发者执行 tbump $NEW_VERSION 即可,tbump 会自动更新版本号、发布版本对应的 git tag,随后仓库的 GitHub Actions 构建发行包并发布到 PyPI。

tbump 的行为由 tbump.toml 配置:当前版本为 1.2.0.dev0,版本号遵循 major.minor.patch[extra] 的 semver 正则;[[file]] 段声明了需要同步打补丁的文件为 setup.py(与上面"更新 <pkg>/_version.py"的通用做法一一对应);git 提交消息模板为 Bump to {new_version}、tag 模板为 v{new_version}。这恰好是把 releasing.rst 通用流程落到具体仓库的实例:版本号维护在源码元数据文件中、提交 + 打 tag + 推送,其余交给 CI。

十一、把指南用起来:构建本仓库文档做实战演练

对想实践"源码安装 + 开发流程"的读者,本仓库自带一套文档构建方案,可以作为上述流程的真实演练场。文档由 Sphinx 驱动,源码位于 docs/source,构建产物输出到 docs/build,采用 reStructuredText 与 MyST Markdown 混写(见 README.md)。

方式一:nox 自动化(推荐)。安装 pip install nox 后执行:

nox -s docs

会基于 Python 3.11 创建虚拟环境、安装 docs/doc-requirements.txt 中的依赖并执行 sphinx-build -b html docs/source docs/build/html(见 noxfile.py)。想要实时预览,可运行 nox -s docs-live,它会用 sphinx-autobuild 启动监听服务器(忽略 docs/build 目录),改文件即自动重建,按 Ctrl-C 停止。

方式二:手动构建。安装 miniconda 后:

conda env create -f environment.yml
source activate jupyter_docs
make clean
make html

产物位于 build/html,可用 python3 -m http.server 起服务,浏览器访问 0.0.0.0:8000 预览。

结语:从贡献者到发布者的完整路径

从本文可以清晰地看到 Jupyter 的协作方法论:小步快跑、尽早开 PR、用测试表达预期、用 milestone 组织发布、用标准命令保证可重复。对贡献者而言,找到 sprint-friendly 的 issue、按 12 步流程提交、围绕五个测试问题打磨用例即可顺利走通;对维护者而言,backport 脚本与 tbump 等工具把合并与发布从"手艺"变成了"流程"。需要进一步深入时,可直接阅读 贡献指南、JEP 提案流程 与 发布模板 原文,它们就是这份指南的完整权威来源。

登录后查看全文
jupyter