我能提供什么帮助？#

为开源做贡献可能是一个令人紧张的过程，但请不要担心，Jupyter 团队的每个人都致力于确保您的开源体验尽可能愉快。在以下描述的任何过程中，您都可以随时通过 Gitter 或邮件列表联系 Jupyter 团队寻求帮助。如果您担心在公共场合提问，也可以私下联系 Jupyter 开发者。您可以使用公共 Gitter 找到最了解您正在处理的代码的人，并通过私人聊天与他们交流。

当您开始您的开源之旅时，请记住，如果您不理解某些内容，没关系；如果您犯了错误，没关系；如果您只贡献了修复您正在处理的问题所需的一小部分代码，也没关系。欢迎任何形式的帮助，并鼓励所有人做出贡献。

提交拉取请求#

欢迎并鼓励个人提交拉取请求并为 Jupyter 源代码做贡献。如果您是第一次贡献者，希望参与 Jupyter，您可以使用以下查询在 GitHub 搜索中查找 Jupyter 代码库中适合初学者的待解决问题。此查询特别有用，因为 Jupyter 代码库分布在 jupyter 组织中的多个存储库中，而不是单个存储库中。您可以点击下面的链接查找适合冲刺的问题。

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

一旦您找到一个渴望解决的问题，您可以使用下面的指南开始。如果在处理问题时遇到任何问题，请在 GitHub 的问题页面上留言，核心团队的成员将能够为您提供帮助。

请记住，以下内容是指导原则。如果您按照步骤操作并有疑问或遇到时间限制，请将您已完成的工作作为拉取请求提交并提出问题。您的努力，包括部分或正在进行的工作，都值得赞赏。

  1. Fork 与您正在解决的问题相关的存储库，并将其克隆到您机器上的本地目录。

  2. cd 进入该目录，并使用 git checkout -b insert-branch-name-here 创建一个新分支。

    选择一个能说明您正在修复的问题的分支名称。例如，如果您正在更新程序在发生特定错误时记录的文本，您可以将分支命名为 update-error-text。

  3. 请参阅存储库的 README 和文档，了解有关为开发配置系统的详细信息。

  4. 确定您将进行代码更改的模块或类，并在文件中留下评论，描述您正在尝试解决的问题。

  5. 向存储库打开一个拉取请求，并在前面附加 [WIP]，以便核心团队知道您正在积极处理该问题。创建拉取请求时，请确保标题清晰简洁地描述您的代码所做的事情。例如，我们可以使用标题“Updated error message on ExampleException”。在拉取请求的正文中，请确保包含短语“Closes #issue-number-here”，其中 issue number 是您在此 PR 中正在处理的问题编号。

    请尽早打开 PR。及早获得关于您方法的回馈将为您节省时间，并防止以后需要进行大量重构。

  6. 在本地运行测试套件，以确保您的系统已正确配置。请参阅存储库的 README，了解如何运行测试套件。这通常需要您在命令行上运行 nosetests 命令。或者，您可以提交拉取请求。我们的持续集成系统将测试您的代码并报告测试结果。

  7. 找到与您将要更改的模块相关的测试文件。在测试文件中，添加一些测试，概述您期望更改的行为。如果我们继续以更新错误时记录的文本为例，我们可能会编写测试用例，检查在诱发错误时引发的异常是否包含适当的字符串。编写测试用例时，请确保测试以下内容。

    • 我能为这个问题编写的最简单的测试用例是什么？

    • 如果您的代码获得杂乱的输入会发生什么？

    • 如果您的代码没有输入会发生什么？

    • 如果您的代码输入太少会发生什么？

    • 如果您的代码输入太多会发生什么？

    如果您在编写测试用例时需要帮助，您可以在之前打开的拉取请求上发表评论，核心团队的成员将能够帮助您。

  8. 回到您正在更新的文件，开始为您的拉取请求添加代码。

  9. 再次运行测试套件，看看您的更改是否导致任何测试用例通过。如果任何测试用例失败，请返回您的代码并进行必要的更新以使其通过。

  10. 一旦所有测试用例都通过，请提交测试用例和更新的模块，并将更新推送到您的分支存储库上的分支。

  11. 一旦您的拉取请求准备好进行审核，请从问题前面删除 [WIP] 标签，项目审核员将审核您的代码质量。您可以期望审核员检查您所做更改中提供的文档、您提供的测试用例的彻底程度以及您的代码效率。您的审核员将提供关于您代码的回馈，您将有机会编辑您的代码并应用修复。

  12. 一旦您的 PR 准备好成为代码库的一部分，它将由核心团队成员合并。

贡献工作流#

A flow chart listing the steps of contributing code to Jupyter with 14 labeled boxes linked by arrows. The chart is uni-directional. At each step, arrows point forward to one or more boxes and back to the previous box or boxes. Refer to the link below the image for full text.

完整的贡献工作流描述。[1]

核心开发者工作流#

为了帮助您了解您提交拉取请求后核心开发者的审查流程，这里有一份指南，概述了通用流程（具体情况可能因存储库而异）。以下是 Jupyter notebook 4.x 的示例。

通常，拉取请求是针对 master 的，除非它们只影响回溯分支。如果 PR 影响 master 并且应该回溯，则一般流程是：

  1. 将 PR 标记为下一个回溯版本 (4.3) 的里程碑

  2. 合并到 master

  3. 回溯到 4.x

  4. 推送更新的 4.x 分支

回溯可以通过多种方式完成，但我们有一个脚本，用于自动化常见的流程：

  1. 下载补丁 例如，<https://patch-diff.githubusercontent.com/raw/jupyter/notebook/pull/1645.patch>

  2. 签出 4.x 分支

  3. 应用补丁

  4. 进行提交

这适用于简单情况，至少如此。

在这种情况下，它将是：

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

提交错误#

在使用 Notebook 时，您可能会遇到表现为意外行为的错误。如果是这样，我们鼓励您在 GitHub 上提出问题。为了让开发者和用户更容易浏览问题，我们要求您在提交问题之前采取以下步骤。

  1. 在 StackOverflow 和现有的 GitHub 问题中搜索，以确保该问题尚未被其他用户报告。如果是这样，如果您认为有价值，请在现有问题上提供您的意见。

  2. 准备一个小的、独立的、可重现您所遇到问题的代码片段。

  3. 准备有关您执行代码的环境信息，以帮助调试问题。在提交错误时，您需要提供有关 Python 版本、Jupyter 版本、操作系统和您正在使用的浏览器信息。您还可以使用 pip list 或 conda list 和 grep 来识别与您提交的问题相关的库版本。

  4. 准备一个简单的测试，概述代码的预期行为，或描述预期行为应该是什么。

  5. 准备一个解释，说明为什么当前行为不理想以及它应该是什么。

报告漏洞#

如果您认为在 Jupyter 项目中发现了安全漏洞，请将其报告给 security@ipython.org。如果您希望加密您的安全报告，可以使用此 PGP 公钥。