为 NumPy 贡献#

不是程序员？没问题！NumPy 是多方面的，我们可以获得很多帮助。这些都是我们希望获得帮助的活动（它们都很重要，因此我们按字母顺序排列）：

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

我们理解每个人经验水平不同，NumPy 也是一个相当成熟的项目，因此很难假设一个理想的“首次贡献者”。这就是为什么我们不使用“good-first-issue”标签来标记问题。相反，您会找到标记为“Sprintable”的问题。这些问题可以是：

在经验丰富的贡献者指导下可以轻松修复（非常适合在冲刺中工作）。
对于那些准备深入探索的人来说，这是一个学习机会，即使您没有参加冲刺。

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

本文档的其余部分讨论了在 NumPy 代码库和文档方面的工作。我们正在更新对其他活动和角色的描述。如果您对这些其他活动感兴趣，请联系我们！您可以通过 numpy-discussion 邮件列表或在 GitHub 上进行（提出问题或在相关问题上评论）。这些是我们首选的沟通渠道（开源本质上是开放的！），但是，如果您更喜欢先在更私密的空间讨论，您可以在 Slack 上进行（详情请参见 numpy.org/contribute）。

开发流程 - 概述#

以下是简短概述，完整的目录链接在下方：

如果您是首次贡献者
- 前往 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）。使用格式正确的提交消息，编写在您的更改之前会失败并在之后通过的测试，在本地运行所有测试。请务必在 docstrings 中记录任何更改的行为，并遵循 NumPy docstring 标准。
提交您的贡献
- 将您的更改推送回 GitHub 上的 Fork
```
git push origin linspace-speedups
```
- 前往 GitHub。新分支将显示一个绿色的 Pull Request 按钮。确保标题和消息清晰、简洁、不言自明。然后点击按钮提交。
- 如果您的提交引入了新功能或更改了现有功能，请在邮件列表上发帖解释您的更改。对于错误修复、文档更新等，通常没有必要这样做，但如果您没有收到任何反馈，请随时请求审阅。
审阅流程
- 审阅者（其他开发人员和感兴趣的社区成员）将在您的 Pull Request (PR) 上撰写内联和/或一般性评论，以帮助您改进其实现、文档和风格。项目中的每一位开发人员的代码都会经过审阅，我们已将其视为一种友好的交流，从中我们所有人都能学习并提高整体代码质量。因此，请不要让审阅阻碍您贡献：它的唯一目的是提高项目质量，而不是批评（毕竟，我们非常感谢您所贡献的时间！）。有关更多信息，请参阅我们的审阅者指南。
- 要更新您的 PR，请在本地仓库中进行更改、提交、运行测试，并且仅在测试成功后推送到您的 fork。一旦这些更改被推送（到与之前相同的分支），PR 将自动更新。如果您不知道如何修复测试失败，您仍然可以推送您的更改并在 PR 评论中寻求帮助。
- 每次 PR 更新后，各种持续集成 (CI) 服务都会被触发，以构建代码、运行单元测试、测量代码覆盖率并检查您分支的编码风格。在您的 PR 可以合并之前，CI 测试必须通过。如果 CI 失败，您可以通过点击“失败”图标（红色叉号）并检查构建和测试日志来找出原因。为了避免过度使用和浪费此资源，请在提交前在本地测试您的工作。
- PR 必须至少获得一名核心团队成员的批准才能合并。批准意味着核心团队成员已仔细审阅了更改，并且 PR 已准备好合并。
文档更改

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

如果您的更改引入了弃用，请务必先在 GitHub 或邮件列表上讨论。如果就弃用达成一致，请遵循NEP 23 弃用策略来添加弃用。
交叉引用问题

如果 PR 与任何问题相关，您可以在 GitHub 评论中添加文本 xref gh-xxxx，其中 xxxx 是问题的编号。同样，如果 PR 解决了某个问题，请将 xref 替换为 closes、fixes 或 GitHub 接受的任何其他形式。

在源代码中，请务必在任何问题或 PR 引用前加上 gh-xxxx。

如需更详细的讨论，请继续阅读并点击本页底部的链接。

指南#

所有代码都应该有测试（详见下面的测试覆盖率）。
所有代码都应有文档。
未经核心团队成员审阅和批准，任何更改都不会被提交。如果您的 Pull Request 在一周内没有收到任何回复，请礼貌地在 PR 或邮件列表上询问。

风格指南#

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

测试覆盖率#

修改代码的 Pull Request (PR) 应该包含新测试，或者修改现有测试，使其在 PR 之前失败并在之后通过。在推送 PR 之前，您应该运行测试。

在本地运行 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 开发工作流程中。