我能提供什么帮助?#

为开源做贡献可能是一个令人紧张的过程,但请不要担心,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 listconda listgrep 来识别与您提交的问题相关的库版本。

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

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

报告漏洞#

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