我能提供什么帮助?#
为开源做贡献可能是一个令人紧张的过程,但请不要担心,Jupyter 团队的每个人都致力于确保您的开源体验尽可能愉快。在以下描述的任何过程中,您都可以随时通过 Gitter 或邮件列表联系 Jupyter 团队寻求帮助。如果您担心在公共场合提问,也可以私下联系 Jupyter 开发者。您可以使用公共 Gitter 找到最了解您正在处理的代码的人,并通过私人聊天与他们交流。
当您开始您的开源之旅时,请记住,如果您不理解某些内容,没关系;如果您犯了错误,没关系;如果您只贡献了修复您正在处理的问题所需的一小部分代码,也没关系。欢迎任何形式的帮助,并鼓励所有人做出贡献。
提交拉取请求#
欢迎并鼓励个人提交拉取请求并为 Jupyter 源代码做贡献。如果您是第一次贡献者,希望参与 Jupyter,您可以使用以下查询在 GitHub 搜索中查找 Jupyter 代码库中适合初学者的待解决问题。此查询特别有用,因为 Jupyter 代码库分布在 jupyter 组织中的多个存储库中,而不是单个存储库中。您可以点击下面的链接查找适合冲刺的问题。
is:issue is:open is:sprint-friendly user:jupyter
一旦您找到一个渴望解决的问题,您可以使用下面的指南开始。如果在处理问题时遇到任何问题,请在 GitHub 的问题页面上留言,核心团队的成员将能够为您提供帮助。
请记住,以下内容是指导原则。如果您按照步骤操作并有疑问或遇到时间限制,请将您已完成的工作作为拉取请求提交并提出问题。您的努力,包括部分或正在进行的工作,都值得赞赏。
Fork 与您正在解决的问题相关的存储库,并将其克隆到您机器上的本地目录。
cd
进入该目录,并使用git checkout -b insert-branch-name-here
创建一个新分支。选择一个能说明您正在修复的问题的分支名称。例如,如果您正在更新程序在发生特定错误时记录的文本,您可以将分支命名为
update-error-text
。请参阅存储库的 README 和文档,了解有关为开发配置系统的详细信息。
确定您将进行代码更改的模块或类,并在文件中留下评论,描述您正在尝试解决的问题。
向存储库打开一个拉取请求,并在前面附加
[WIP]
,以便核心团队知道您正在积极处理该问题。创建拉取请求时,请确保标题清晰简洁地描述您的代码所做的事情。例如,我们可以使用标题“Updated error message on ExampleException”。在拉取请求的正文中,请确保包含短语“Closes #issue-number-here”,其中 issue number 是您在此 PR 中正在处理的问题编号。请尽早打开 PR。及早获得关于您方法的回馈将为您节省时间,并防止以后需要进行大量重构。
在本地运行测试套件,以确保您的系统已正确配置。请参阅存储库的 README,了解如何运行测试套件。这通常需要您在命令行上运行
nosetests
命令。或者,您可以提交拉取请求。我们的持续集成系统将测试您的代码并报告测试结果。找到与您将要更改的模块相关的测试文件。在测试文件中,添加一些测试,概述您期望更改的行为。如果我们继续以更新错误时记录的文本为例,我们可能会编写测试用例,检查在诱发错误时引发的异常是否包含适当的字符串。编写测试用例时,请确保测试以下内容。
我能为这个问题编写的最简单的测试用例是什么?
如果您的代码获得杂乱的输入会发生什么?
如果您的代码没有输入会发生什么?
如果您的代码输入太少会发生什么?
如果您的代码输入太多会发生什么?
如果您在编写测试用例时需要帮助,您可以在之前打开的拉取请求上发表评论,核心团队的成员将能够帮助您。
回到您正在更新的文件,开始为您的拉取请求添加代码。
再次运行测试套件,看看您的更改是否导致任何测试用例通过。如果任何测试用例失败,请返回您的代码并进行必要的更新以使其通过。
一旦所有测试用例都通过,请提交测试用例和更新的模块,并将更新推送到您的分支存储库上的分支。
一旦您的拉取请求准备好进行审核,请从问题前面删除 [WIP] 标签,项目审核员将审核您的代码质量。您可以期望审核员检查您所做更改中提供的文档、您提供的测试用例的彻底程度以及您的代码效率。您的审核员将提供关于您代码的回馈,您将有机会编辑您的代码并应用修复。
一旦您的 PR 准备好成为代码库的一部分,它将由核心团队成员合并。
贡献工作流#

完整的贡献工作流描述。[1]
核心开发者工作流#
为了帮助您了解您提交拉取请求后核心开发者的审查流程,这里有一份指南,概述了通用流程(具体情况可能因存储库而异)。以下是 Jupyter notebook 4.x
的示例。
通常,拉取请求是针对 master
的,除非它们只影响回溯分支。如果 PR 影响 master 并且应该回溯,则一般流程是:
将 PR 标记为下一个回溯版本 (4.3) 的里程碑
合并到 master
回溯到 4.x
推送更新的 4.x 分支
回溯可以通过多种方式完成,但我们有一个脚本,用于自动化常见的流程:
下载补丁
例如,<https://patch-diff.githubusercontent.com/raw/jupyter/notebook/pull/1645.patch>
签出 4.x 分支
应用补丁
进行提交
这适用于简单情况,至少如此。
在这种情况下,它将是:
python /path/to/ipython-repo/tools/backport_pr.py jupyter/notebook 4.x 1645
提交错误#
在使用 Notebook 时,您可能会遇到表现为意外行为的错误。如果是这样,我们鼓励您在 GitHub 上提出问题。为了让开发者和用户更容易浏览问题,我们要求您在提交问题之前采取以下步骤。
在 StackOverflow 和现有的 GitHub 问题中搜索,以确保该问题尚未被其他用户报告。如果是这样,如果您认为有价值,请在现有问题上提供您的意见。
准备一个小的、独立的、可重现您所遇到问题的代码片段。
准备有关您执行代码的环境信息,以帮助调试问题。在提交错误时,您需要提供有关 Python 版本、Jupyter 版本、操作系统和您正在使用的浏览器信息。您还可以使用
pip list
或conda list
和grep
来识别与您提交的问题相关的库版本。准备一个简单的测试,概述代码的预期行为,或描述预期行为应该是什么。
准备一个解释,说明为什么当前行为不理想以及它应该是什么。
报告漏洞#
如果您认为在 Jupyter 项目中发现了安全漏洞,请将其报告给 security@ipython.org
。如果您希望加密您的安全报告,可以使用此 PGP 公钥。