Jupyter 开发者指南:从源码安装、提交 PR 到版本发布的完整协作流程
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 提交流程,完整步骤如下:
- Fork 并克隆:Fork 与 issue 对应的仓库,克隆到本地目录。
- 创建分支:
cd进目录后执行git checkout -b insert-branch-name-here。分支名应体现要解决的问题,例如更新某错误日志文本时,可命名为update-error-text。 - 配置开发环境:参考目标仓库的 README 与文档,完成系统级开发环境配置。
- 定位代码位置:确定改动所在的模块或类,并在文件内留下注释,说明你试图解决哪个 issue。
- 尽早开 PR:向仓库提交 Pull Request,并在标题前加
[WIP],让核心团队知道你正在积极跟进。PR 标题应简洁准确地描述代码行为(例如 "Updated error message on ExampleException"),PR 描述中务必包含Closes #issue-number-here(替换为实际 issue 号)。越早开 PR,越早获得方向性反馈,可以避免后期大范围重构。 - 运行测试套件:在本地跑测试,确认环境配置正确。具体命令参考目标仓库 README(文档给出的传统方式是命令行执行
nosetests);也可以直接提交 PR,让 CI 系统代为测试并报告结果。 - 编写测试用例:找到与被改模块对应的测试文件,添加能描述预期行为的测试。例如,若你改了异常日志文本,可以写测试断言"触发该错误时抛出的异常包含相应字符串"。写测试时至少思考以下几点:
- 针对该 issue,我能写的最简测试是什么?
- 代码收到"脏"输入时会发生什么?
- 代码收到空输入时会发生什么?
- 代码收到过少输入时会发生什么?
- 代码收到过多输入时会发生什么?
- 需要帮助时可以在此前开的 PR 下留言,核心成员会协助。
- 实现代码:回到要修改的文件,开始编写 PR 对应的实现代码。
- 再次运行测试:确认改动是否让用例通过;若有失败,回头修改代码直到通过。
- 提交并推送:全部用例通过后,同时提交测试用例与修改后的模块,推送到 fork 仓库的分支。
- 请求评审:准备好被评审后,去掉标题前的
[WIP]标签。评审人会重点检查三方面:改动附带的文档、测试用例的完备程度、代码效率。评审会给出反馈,你有机会据此修改并重新提交。 - 合并:PR 达到入库标准后,由核心团队成员合并进主分支。
五、贡献工作流:14 节点流程全景
下面的流程图(出自原贡献指南,见 contrib_guide.md)用 14 个节点串起了从"开始"到"庆祝并继续"的单向贡献流程,每个节点可前进到下一步,也可能回退到上一步:
该流程的文字版描述如下:
- 开始 → 找到要解决的 issue
- 找到要解决的 issue → 定位代码库中的相关模块
- 定位相关模块 → 编写简单的测试用例,验证你的修复或增强能正常工作
- 编写测试用例 → 在合适位置实现 Bug 修复或增强功能
- 实现修复/增强 → 运行测试套件,确认更新后的代码工作正常
- 运行测试套件 → 分支:测试通过! 或 测试失败!
- 测试失败 → 定位并修复新代码中导致错误的问题;可参考邮件列表或 Zulip 频道求助
- 修复问题 → 回到"运行测试套件"
- 测试通过! → 向对应仓库提交包含优秀代码的 Pull Request
- 提交 PR → 分支:评审人批准并合并 或 评审人要求修改
- 评审人要求修改 → 对 PR 应用必要修复或更新
- 应用修改 → 回到"提交 PR"
- 评审人批准并合并 PR → 庆祝并重复
- 庆祝并重复!(流程回到起点,迎接下一个贡献)
六、核心开发者工作流:合并与 backport
提交 PR 之后,核心开发者的评审与合并过程遵循一套通用流程(各仓库细节略有差异),文档以 Jupyter Notebook 4.x 为例展开。
一般而言,PR 默认合入 master 分支,除非它只影响 backport 分支。如果一个 PR 同时影响 master 且需要 backport,标准流程为:
- 为 PR 标记下一个 backport 版本(例如 4.3)的 milestone;
- 合并进 master;
- backport 到 4.x 分支;
- 推送更新后的 4.x 分支。
backport 有多种实现方式,Jupyter 社区维护了一个脚本来自动化常见流程(参考 IPython 仓库的 tools/backport_pr.py),其核心动作是:
- 下载补丁(例如
jupyter/notebook的 PR #1645 对应补丁); - 检出 4.x 分支;
- 应用补丁;
- 提交。
这个脚本至少对简单场景是有效的。实际调用示例:
python /path/to/ipython-repo/tools/backport_pr.py jupyter/notebook 4.x 1645
七、提交 Bug 报告:让问题可复现、可定位
使用 Notebook 时遇到异常行为,欢迎到 GitHub 提 issue。为了让开发者和用户都能高效地在 issue 列表中导航,提交前请依次完成:
- 先搜索:在 StackOverflow 和已有 GitHub issues 中检索,确认该问题尚未被报告过;若已有相关 issue,可在其上补充你认为有价值的输入。
- 准备最小复现片段:写一段小而自包含的代码,让其他人能据此复现问题。
- 准备环境信息:提供 Python 版本、Jupyter 版本、操作系统、浏览器等信息,便于调试。可用
pip list或conda list配合grep快速筛出与问题相关的库版本。 - 准备预期行为:写一个能描述代码预期行为的简单测试,或一段对预期行为的文字描述。
- 解释差异:说明为什么当前行为不符合预期、期望的行为应该是什么。
八、报告安全漏洞
如果你认为在某个 Jupyter 项目中发现了安全漏洞,请将其报告至 security@ipython.org;若希望加密发送安全报告,可以使用该项目公布的 PGP 公钥进行加密。安全漏洞报告应独立于普通 issue 处理,以保证修复窗口期的信息控制。
九、Jupyter Enhancement Proposals(JEP)提交流程
在使用 Notebook 过程中发现值得改进的方向或新功能需求时,可以提交增强提案。提交流程如下:
- 界定范围:判断增强只影响代码库的哪一部分、实现是否足够简单。小范围的增强应作为 issue 提交到项目仓库;大范围的增强则应提交到官方的 Jupyter Enhancement Proposals 仓库。
- 写问题描述:简要说明你的增强要解决的问题。
- 写方案描述:简要说明你提议的增强本身。
- 写实现草案:如果第 1 步判定为大规模增强,则需要详细写出潜在的实现方案。
- 列出利弊:给出实现该增强的简要优点与缺点清单。
- 识别相关人员:找出可能对实现该增强感兴趣的人。
- 提交:根据范围,选择提交为仓库 issue,或提交为正式的 Jupyter Enhancement Proposal(JEP)。
十、发布一个 Jupyter 项目:从 Milestone 到 PyPI
releasing.rst 提供了一套"小而美"项目的发布模板,大项目也适用,只是可能多出一些步骤。Jupyter 生态由若干小项目加少量大项目构成,以下流程是标准发布路径。
10.1 Milestone:发布的前置准备
多数 Jupyter 项目用 GitHub 的 milestone 系统来为 issue 和 PR 归类到具体版本。每个发布都应有对应的 milestone,准备发布的第一步是确保每个 issue 和 PR 都有正确的 milestone:
- 检查标记为当前 milestone 的所有未关闭 issue 和 PR:若有遗留,需在本次发布前解决,或把它们"提升"(bump)到下一个 milestone。把 issue 提升是常见做法——它们通常被乐观地标上最早可行的版本,但发布时刻未必都完成。
- 检查已关闭的 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 提案流程 与 发布模板 原文,它们就是这份指南的完整权威来源。
