为 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 上发布信息以解释你的更改.对于 bug 修复,文档更新等,通常没有必要这么做,但如果你没有收到任何反应,请随时提出审查请求.
审查流程:
- 审查者(其他开发者和感兴趣的社区成员)将会在你的 Pull Request (PR) 上编写内联和/或一般性评论,以帮助你改进其实现,文档和风格.每一个参与该项目的开发者都要经过代码审查,我们已经将其看作是一种友好的交流,我们从中学习,并提高整体代码质量.因此,请不要因为审查而感到气馁:审查的唯一目的是提高项目质量,而不是批评(毕竟,我们非常感谢你所贡献的时间!).有关更多信息,请参阅我们的 Reviewer Guidelines .
- 要更新你的 PR,请在你本地仓库中进行更改,提交,运行测试,只有在测试通过的情况下才推送至你的 fork.一旦这些更改被推送(到与之前相同的分支),PR 将会自动更新.如果你不知道如何修复测试失败,你可以先推送更改,然后在 PR 评论中寻求帮助.
- 各种持续集成 (CI) 服务会在每次 PR 更新后触发,以构建代码,运行单元测试,测量代码覆盖率以及检查你分支的编码风格.CI 测试必须通过,你的 PR 才能被合并. 如果 CI 失败, 你可以点击 “failed” 图标(红色叉号)并查看构建和测试日志,找出失败原因.为了避免过度使用和浪费资源,请在提交之前在本地 test your work .
- PR 必须至少获得一位核心团队成员的批准才能合并. 批准意味着核心团队成员已经仔细审查了更改,并且 PR 已准备好合并.
文档更改

除了对函数的 docstring 以及通用文档中可能的描述进行更改之外,如果你的更改引入了任何面向用户的修改,则可能需要在发行说明中提及. 要将你的更改添加到发行说明中,你需要创建一个包含摘要的简短文件,并将其放置在 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 解决了问题,请将 xref 替换为 closes , fixes 或任何其他 github accepts 接受的风格.

在源代码中,请务必在任何 issue 或 PR 引用前加上 gh-xxxx .

要进行更详细的讨论,请继续阅读并点击本页面底部的链接.

指南#

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

风格指南#

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

测试覆盖率#

修改代码的拉取请求 (PRs) 应该有新的测试,或者修改现有的测试,使其在 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 中.