Jupyter 贡献者指南：全面参与文档、代码与社区建设的实战路径-平芜编程栈

开发工具

【免费下载链接】jupyter

Jupyter metapackage for installation and documentation

项目地址：https://gitcode.com/gh_mirrors/ju/jupyter

本文基于 Jupyter 项目官方贡献指南（docs/source/contributing/content-contributor.rst）及其配套的开发者指南、文档贡献指南与沟通贡献指南，系统梳理 Jupyter 生态的贡献方式、完整工作流与工具链。读者读完本文后，将掌握三条可落地的参与路径——改进文档（含本地构建与验证）、贡献代码（含开发环境搭建）以及参与社区运营（博客、通讯稿与网站），并了解申请 Jupyter 受管账号的具体渠道。

欢迎加入：Jupyter 需要每一位贡献者

无论你是初次接触开源的新人、回归的老面孔，还是长期活跃的维护者，Jupyter 社区都真诚地欢迎你的加入。Jupyter 在过去几年持续成长，社区成员数量与使用场景不断扩展，这给项目维护者带来了更多的需求与资源压力。因此，官方指南明确要求贡献者花时间熟悉贡献流程，了解项目沟通方式与协作惯例，再开始行动。

如果对贡献流程有任何疑问，可以直接在社区中提问。Jupyter 社区维护着一套公开的沟通渠道（包括邮件列表、Zulip/Discourse 讨论组与定期社区会议），这些常用沟通方式在 docs/source/community/content-community.rst 中有集中说明。

贡献价值是被明确肯定的：无论贡献的是代码、文档、教学资源，还是社区对话中的积极参与，都会被接纳和珍视。下面按官方指南的结构，逐一展开各类贡献方式及其可操作的路径。

一、贡献方式全景：文档、代码与社区

官方指南在"我可以做哪些贡献"（What kinds of contributions can I make）一节中给出了三大类贡献方向，并强调这份清单并非穷尽——只要你能想到任何能带来改进的方式，社区都欢迎。

1. 改进文档

文档是 Jupyter 生态中最关键的部分之一。好的文档让用户更容易学会使用工具，也让教学、维护和代码改进变得更加容易。具体贡献方式包括：

阅读教程并报告令人困惑的部分——以"第一个读者"的身份反馈文档盲区；
发现文档中的拼写错误和细节问题——提交 typo 修复或作为 bug 上报；
撰写自己的指南与教程——面向真实使用场景补充实战内容；
改进代码内的 docstring——提升 API 层面的可读性；
改进文档的风格与设计——优化结构、版式与信息呈现。

想系统参与文档工作，官方推荐从 :ref:documentation-guide（即 docs/source/contributing/docs-contributions/index.rst）入手，本文第二部分会详细展开。

2. 贡献代码

Jupyter 生态由大量代码仓库组成，分散在多个 GitHub 组织下，覆盖交互式计算的方方面面，包括用户界面（如 JupyterLab、Notebook）、内核（如 IPython kernel）、共享基础设施（如 Jupyter Server、nbformat）、交互式控件（如 ipywidgets）以及结构化文档（如 nbconvert、nbdime）等。

官方推荐先阅读 :ref:developer-guide（即 docs/source/contributing/dev-contributions/index.rst），在其中找到最合适的项目与下一步行动。本文第三部分会展开。

3. 参与社区

Jupyter 最重要的是它的社区——一个遍布全球、多元化的群体。参与社区本身就是一种高质量贡献：

参与在线讨论，在讨论组中回答问题、分享经验；
主动帮助他人解决使用或开发问题；
参加社区会议（例如 docs/source/community/community-call-notes 中记录的历次会议纪要所对应的例会机制）；
向他人讲授 Jupyter，扩大生态影响力。

社区相关细节由 :ref:community-guide（即 docs/source/contributing/communication-contributions.rst）承载，本文第四部分会展开。

二、文档贡献全流程：从第一个 typo 到正式发布

Jupyter 的文档贡献有标准化的流程，覆盖从环境准备、源码编辑、本地测试到提交 Pull Request 的完整闭环。

2.1 技术栈速览

根据 docs/source/contributing/docs-contributions/getting-started.rst 与 docs/source/contributing/docs-contributions/doc-tools.rst，Jupyter 文档体系建立在四块基石上：

源文件格式：reStructuredText（.rst）、Markdown（.md）与 Jupyter Notebook（.ipynb）三种格式并存；
构建工具：广泛使用 Sphinx 构建文档；
翻译机制：使用 Transifex 将文档翻译为多种语言；
托管平台：文档部署在 Read the Docs 上。

其中 Sphinx 是用户文档、贡献者指南与沟通内容的主构建工具；对于开发者 API 文档（尤其是 JupyterLab 的 JS 仓库），则使用 Swagger。主题方面，Jupyter 各项目目前主要使用sphinx_rtd_theme，ipywidgets 则使用jupyter_sphinx_theme。

以本仓库为例，docs/source/conf.py 是 Sphinx 配置入口，docs/Makefile 与 docs/make.bat 提供构建命令，docs/environment.yml 与 docs/doc-requirements.txt 声明构建依赖，docs/source/locale/ 下的*.po文件（en/es/pt_BR等多语言目录）正是 Transifex 翻译流程在仓库中的落地产物。

2.2 文档仓库的标准结构

在动手之前，理解文档在仓库中的位置很重要。docs/source/contributing/docs-contributions/repo-structure.md 给出了标准布局：

仓库根目录：docs目录存放全部文档源文件；readthedocs.yml用于配置 Read the Docs 使用 conda 构建；
docs 目录内部：source目录存放全部.rst/.md/.ipynb内容源文件；Makefile供 Sphinx 构建；environment.yml提供 conda 构建指令；
source 目录内部：conf.py为 Sphinx 配置文件；index.rst（或contents.rst）为 Sphinx 主目录文件；_static目录存放图片、插画与图标；_templates目录覆盖主题模板与布局；build目录存放 Sphinx 生成的 HTML（切勿提交到 GitHub）。

当前仓库完全遵循这一布局：docs/source 下的contributing/（贡献指南）、community/（社区内容）、projects/（项目介绍）、use/（使用指南）等目录即是典型的分层组织方式。

2.3 首次文档贡献的实操步骤

根据 getting-started.rst 的指引，完整步骤如下：

第一步：准备环境。确认文档体系使用 reStructuredText、Markdown 和 Jupyter Notebook 三种源格式，并通过 Sphinx 构建。

第二步：克隆仓库。在 GitHub 上 fork 目标项目仓库，然后克隆到本地。项目文档源文件通常位于各仓库的docs/source目录下，reStructuredText 文件以.rst结尾，Notebook 文件以.ipynb结尾。

第三步：编辑源文件。在文本编辑器中修改.rst文件；如需编辑.ipynb文件，需要先按 docs/source/install.rst 安装 Jupyter Notebook，运行后编辑对应文件，保存前务必清空输出单元格（clear the output cells），以减少无意义的 diff。

第四步：本地测试。Sphinx 必须安装才能验证改动。官方推荐安装 Sphinx 稳定开发版或当前发布版：

# 方式一：稳定开发版 pip install git+https://github.com/sphinx-doc/sphinx@stable # 方式二：当前发布版 pip install sphinx

此外还需要以下配套包：

pip install sphinxcontrib-spelling sphinx_rtd_theme nbsphinx pyenchant recommonmark==0.4.0 jupyter_sphinx_theme

Linux 用户还需安装 Enchant C 库：sudo apt-get install enchant。文档构建建议使用 Python 3.4+（仅编辑文档时 Python 2.7.9+ 或 GitHub 在线编辑器也可接受，此要求以项目实际运行环境为准）。

在docs目录下执行以下命令验证改动：

make html # 构建本地 HTML 版文档，输出错误信息或 HTML 文档位置 # 例如构建产物位于 build/html，可用 open build/html/index.html 在浏览器查看 make linkcheck # 检查文档中的外部链接是否有效（例如是否已失效导致 500 错误）

第五步：提交 Pull Request。改动满意后在 GitHub 上提交 PR。如果改动与某个已开 issue 相关，请在 PR 描述中提及该 issue 编号。项目评审者会审阅改动并给出反馈，或直接合入。

第六步：提问。任何阶段都可以在 Jupyter 的 Google Group 或 GitHub 对应 issue 中提问，无需独自硬扛。

2.4 高层文档工作流（八步法）

docs/source/contributing/docs-contributions/doc-workflow.rst 将上述过程总结为可复制的八步工作流：

识别文档改动需求：
- 拼写错误：直接修复（或作为 bug 上报）；
- 已开 issue：在 issue 评论区留言说明你在处理；
- 新文档：先开 issue 提出想法，团队评审后与你一起确定下一步；
更新源文件；
提交（commit）改动；
本地测试改动；
打开 Pull Request；
检查自动化测试结果：通过则等待评审反馈与合入；报错则修订后重新提交（无需新开 PR，必要时可求助）；
庆祝你的文档贡献；
重复以上循环，需要新任务建议时可直接询问维护者。

2.5 按子项目找文档 issue

各子项目文档分散维护，docs/source/contributing/docs-contributions/doc-issues-hub.md 提供了快速入口，可按documentation标签检索各子项目的文档类 issue：Jupyter.org 元项目、Jupyter Notebook、JupyterLab、Jupyter Server、JupyterHub、ipywidgets 均维护独立的 issue 列表。这意味着新手可以根据自己熟悉的项目精准切入。

三、代码贡献：找到正确的仓库并搭建开发环境

3.1 开发者指南总览

docs/source/contributing/dev-contributions/index.rst 是代码贡献的总入口，其下还包含三份重要子文档：

contrib_guide.md：通用贡献流程规范；
jupyter_enhancement_proposals.rst：Jupyter 增强提案（JEP）机制，面向跨项目的重大设计变更；
releasing.rst：版本发布流程。

大部分 Jupyter 包都可以像普通 Python 包一样从源码目录安装：

pip install .

需要特别说明的是，Jupyter Notebook 的源码安装还需要额外构建 JavaScript 组件，具体步骤参见 notebook 的贡献者文档中"搭建开发环境"（Setting up a development environment）一节。

3.2 从哪个仓库开始？

docs/source/contributing/start-contributing.rst 给出了按技术栈划分的仓库地图：

Python 主导：IPython、nbgrader、JupyterHub、repo2docker、Binder。每个仓库均维护good first issue或help wanted标签，并有各自的开发安装说明（见各仓库CONTRIBUTING.md或README.md）；
JavaScript/TypeScript：Jupyter Notebook、JupyterLab、IPyWidgets；
DevOps：JupyterHub、repo2docker、Binder 存在大量部署运维类 issue；
Web 开发：Project Jupyter 官网（jupyter.github.io 仓库）的网站相关问题。

初次贡献者应注意两个惯例：一是仓库通常用good first issue/help wanted标签标记适合新人的 issue；二是决定处理某个 issue 前，先在评论区留言告知大家"我来做这个"，避免与他人撞车。若发现开发安装文档有误，务必在 issue 中反馈，项目方高度重视安装文档的准确性。

此外，Jupyter 社区奉行包容、欢迎的文化，参与前请阅读社区的《行为准则》（Code of Conduct）。

四、社区参与与沟通贡献：博客、通讯稿与网站

docs/source/contributing/communication-contributions.rst 定义了非代码类贡献的完整规范，涵盖三大载体。

4.1 Jupyter 博客（Blog）

Jupyter 博客基于 Ghost 平台部署，看重其贡献者灵活性与易用性。从想法到发布的工作流为：产生写作灵感 → 在邮件列表联系作者账号申请 → 创建草稿 → 草稿评审 → 编辑接受 → 发布。

草稿阶段有明确的质量要求：

标题与元数据：发布前务必检查标题与 canonical URL。为 jupyter-day 这类可多次举办的活动写稿时，可在 canonical URL 中放入日期（活动日期可与博文日期不同）。文章一旦发布，绝不修改标题或 URL——这会破坏已被推文和 RSS 引用的链接；部分平台发布时会立即缓存 URL，改标题会把读者引向 404 页面。作为客座作者无需操心元数据，编辑或管理员会处理；
图片处理：尽量不链接外部图片。需要插图时，在编辑视图插入![]()后从桌面拖拽图片到预览区新建的字段中。外部图片可能被删除导致博文失效，而拖拽上传的图片与博客共用同一 CDN，能为读者提供最佳体验。博客顶部封面图（featured image）通过元数据字段设置，而非![]()——许多阅读器（尤其移动端）对封面图与内嵌图处理方式不同，封面图机制让慢速网络用户更早读到正文；
链接规范：尽量不使用短链接（minified links），多次重定向会降低移动端浏览体验；如需阅读量统计，Google Analytics 会负责追踪。

草稿评审强调团队协作："完成初稿后请他人通读并核查易遗漏的参数。你并非孤军奋战，这是团队工作。仓促行事往往比一开始做对花更多时间修补错误。"发布通常由编辑/管理员执行，其职责是核验元数据、杜绝外部图片并完成所有前述质量检查。

对已发布文章，博客订阅者会在每次更新时收到通知，因此更新要节制——等几小时修一个 typo 完全没问题。若需重大更新（如地点、时间的变更），在博文顶部（或按重要性置于底部）插入带更新日期时间的[Update]区块；正文中过时的信息尽量不直接替换，而用删除线标记为废弃，帮助读者在信息源冲突时判断正误。

4.2 通讯稿（Newsletter）

Jupyter 定期发布通讯稿，通过邮件与官网同步社区的重要更新、活动、发布信息。有公告、活动或更新需要分享时，可将拟发布内容邮件提交给核心团队。内容规范包括：保持简短清晰、切中要点；包含相关日期、链接与联系方式；语法正确并尽量避免行话；提交图片或 Logo 时附带 alt 文本描述。通讯稿通常按月或季度发布，往期内容归档于官网，并在后续沟通中提供引用链接。

4.3 官网（Website）

Jupyter 官网（jupyter.org）是访问项目信息、文档、下载与社区资源的主要门户，由静态站点生成器构建，内容涵盖生态总览、JupyterLab/Jupyter Notebook 等关键项目链接、教程与入门指南、社区与贡献者信息。官网通过 GitHub Pages 部署，合并到主分支即自动更新。

贡献方式与文档一致：fork 仓库 → 做出改动 → 提交 Pull Request，走与其他文档相同的评审流程，并遵循项目的风格与语气。提交前务必在本地测试改动（参见各仓库 README 的快速本地测试说明）。

五、申请 Jupyter 受管账号

作为贡献者，你可能需要访问 Jupyter 管理的账号，例如发布博客文章或更新 Jupyter 站点上的信息。官方指南给出了明确渠道：发送邮件至安全组security@ipython.org，或在 Jupyter Security 子项目仓库提交 issue 提出申请。

结语：选择你的切入点

Jupyter 的贡献生态是分层的：文档贡献门槛最低、反馈最快，是熟悉协作流程的理想起点；代码贡献需要按技术栈选择仓库并遵循各仓库的开发安装说明；社区参与则把价值延伸到内容传播与用户支持。三者在流程上高度一致——fork、修改、本地验证、提交 PR、等待评审——而差异在于各自的工具链与验收标准。

建议新贡献者按官方指南的惯例行动：先阅读所在仓库的CONTRIBUTING.md/README.md，认领带good first issue或help wanted标签的 issue 并在评论区打招呼，用make html和make linkcheck这类可复现的本地验证命令自检，再提交 PR。这套"先熟悉流程、再动手改进"的方法论，正是 Jupyter 社区保持健康协作节奏的关键。