为 NumPy 做贡献#

不是程序员?没问题!NumPy 是多方面的,我们可以获得很多帮助.以下是我们希望获得帮助的所有活动(它们都很重要,因此我们按字母顺序列出它们):

代码维护和开发
社区协调
DevOps
开发教育内容和叙述性文档
筹款
营销
项目管理
翻译内容
网站设计和开发
编写技术文档

我们理解每个人都有不同的经验水平,而且 NumPy 是一个相当完善的项目,因此很难对理想的“首次贡献者”做出假设.因此,这就是我们不使用“good-first-issue”标签标记问题的原因.相反,您会发现 issues labeled “Sprintable” .这些问题可以是:

当您获得经验丰富的贡献者的指导时,可以轻松修复(非常适合在 sprint 中工作).
对于那些准备深入研究的人来说,这是一个学习机会,即使您不在 sprint 中也是如此.

此外,根据您之前的经验,一些“Sprintable”问题可能很容易,而另一些问题可能对您来说更具挑战性.

本文档的其余部分讨论了在 NumPy 代码库和文档上的工作.我们正在更新我们对其他活动和角色的描述.如果您对这些其他活动感兴趣,请联系我们!您可以通过 numpy-discussion mailing list 或 GitHub (打开一个 issue 或评论一个相关 issue)来做到这一点.这些是我们首选的沟通渠道(开源本质上是开放的!),但是如果您希望先在更私密的空间中讨论,您可以在 Slack 上进行(有关详细信息,请参阅 numpy.org/contribute ).

开发流程 - 总结#

这里是一个简短的总结,完整的TOC链接在下方:

如果您是首次贡献者:
- 访问 numpy/numpy 并点击 “fork” 按钮来创建您自己的项目副本.
- 将项目克隆到您的本地计算机:
```
git clone --recurse-submodules https://github.com/your-username/numpy.git
```
- 更改目录:
```
cd numpy
```
- 添加上游仓库:
```
git remote add upstream https://github.com/numpy/numpy.git
```
- 现在, git remote -v 将显示两个远程仓库,命名为:
  - upstream ,指的是 numpy 仓库
  - origin ,指的是您的个人fork
- 从上游拉取最新的更改,包括标签:
```
git checkout main
git pull upstream main --tags
```
- 初始化numpy的子模块:
```
git submodule update --init
```
开发您的贡献:
- 为您要处理的功能创建一个分支.由于分支名称将出现在合并消息中,请使用一个明智的名称,例如 ‘linspace-speedups’:
```
git checkout -b linspace-speedups
```
- 在您进行的过程中在本地提交 ( git add 和 git commit ).使用 properly formatted 提交消息,编写在您更改之前失败并在之后通过的测试,运行所有 tests locally .请务必在文档字符串中记录任何已更改的行为,并遵守 NumPy 文档字符串 standard .
要提交您的贡献:
- 将您的更改推送回您在GitHub上的fork:
```
git push origin linspace-speedups
```
- 转到GitHub.新分支将显示一个绿色的Pull Request按钮.确保标题和消息清晰,简洁且不言自明.然后单击该按钮提交它.
- 如果您的提交引入了新功能或更改了功能,请在 mailing list 上发布以解释您的更改.对于错误修复,文档更新等,通常不需要这样做,但如果您没有得到任何回应,请随时要求进行审查.
审查流程:
- 审阅者(其他开发人员和感兴趣的社区成员)将在您的Pull Request(PR)上写内联和/或一般性评论,以帮助您改进其实施,文档和风格.在项目上工作的每个开发人员都会对其代码进行审查,我们已经将其视为友好的对话,我们从中学习,并且总体代码质量受益.因此,请不要让审查阻止您做出贡献:它的唯一目的是提高项目质量,而不是批评(毕竟,我们非常感谢您捐赠的时间!).请参阅我们的 Reviewer Guidelines 以获取更多信息.
- 要更新您的PR,请在您的本地仓库上进行更改,提交,运行测试,并且只有在它们成功的情况下才推送到你的fork.一旦这些更改被推送(与之前相同的分支),PR将自动更新.如果您不知道如何修复测试失败,您可以推送您的更改,并在PR评论中寻求帮助.
- 在每次PR更新后,将触发各种持续集成(CI)服务,以构建代码,运行单元测试,测量代码覆盖率并检查分支的编码风格.CI测试必须通过,您的PR才能合并.如果 CI 失败,你可以点击 “failed” 图标 (红色叉号) 并查看构建和测试日志,找出原因.为了避免过度使用和浪费此资源,请在提交之前在本地 test your work .
- PR必须至少获得一名核心团队成员的批准才能合并.批准意味着核心团队成员已经仔细审查了更改,并且PR已准备好合并.
文档变更

除了修改函数的文档字符串以及在通用文档中可能出现的描述之外,如果你的更改引入了任何面向用户的修改,那么可能需要在发布说明中提及它们.要将你的更改添加到发布说明中,你需要创建一个包含摘要的简短文件,并将其放置在 doc/release/upcoming_changes 中.文件 doc/release/upcoming_changes/README.rst 详细说明了格式和文件名约定.

如果你的更改引入了弃用,请务必首先在 GitHub 或邮件列表中讨论此事.如果就弃用达成一致,请遵循 NEP 23 deprecation policy 添加弃用.
交叉引用 issue

如果 PR 与任何 issue 相关,你可以向 github 评论添加文本 xref gh-xxxx ,其中 xxxx 是 issue 的编号.同样,如果 PR 解决了 issue,请将 xref 替换为 closes , fixes 或 github 接受的任何其他风格 github accepts .

在源代码中,请务必用 gh-xxxx 作为任何 issue 或 PR 引用的前缀.

有关更详细的讨论,请继续阅读并点击本页底部的链接.

准则#

所有代码都应该有测试(有关更多详细信息,请参见下面的 test coverage ).
所有代码都应该是 documented 的.
未经核心团队成员的审查和批准,任何更改都不会被提交. 如果在一周内没有收到对你的 pull request 的回复,请礼貌地在 PR 上或在 mailing list 上询问.

风格指南#

设置你的编辑器以遵循 PEP 8 (删除尾随空白,禁止制表符等).使用 ruff 检查代码.
使用 NumPy 数据类型而不是字符串( np.uint8 而不是 "uint8" ).
使用以下导入约定:
```
import numpy as np
```
对于 C 代码,请参见 NEP 45 .

测试覆盖率#

修改代码的 Pull Request (PR) 应该有新的测试,或者修改现有的测试,使其在 PR 之前失败,之后通过.你应该在推送 PR 之前 run the tests .

在本地运行 NumPy 的测试套件需要一些额外的包,例如 pytest 和 hypothesis . 额外的测试依赖项在顶级目录的 requirements/test_requirements.txt 中列出,可以使用以下命令方便地安装:

$ python -m pip install -r requirements/test_requirements.txt

模块的测试应理想地覆盖该模块中的所有代码,即,语句覆盖率应达到 100％.

要测量测试覆盖率,请运行:

$ spin test --coverage

这将在 build/coverage 中创建一个 html 格式的报告,可以使用你的浏览器查看,例如:

$ firefox build/coverage/index.html

构建文档#

要构建 HTML 文档,请使用:

spin docs

你也可以从 doc 目录运行 make . make help 列出所有目标.

要获取适当的依赖项和其他要求,请参见构建 NumPy API 和参考文档 .

开发过程 - 详细信息#

故事的其余部分

NumPy 特定的工作流程在 numpy-development-workflow 中.