审阅者指南#

审阅开放的拉取请求（PRs）有助于项目向前发展。我们鼓励项目以外的人员也参与进来；这是熟悉代码库的好方法。

谁可以成为审阅者？#

审阅可以来自 NumPy 团队之外——我们欢迎领域专家（例如，linalg 或 fft）或其他项目的维护者做出贡献。您不需要是 NumPy 维护者（一个有权限合并 PR 的 NumPy 团队成员）即可进行审阅。

如果我们还不认识您，在开始审阅拉取请求之前，请考虑在邮件列表或 Slack 中介绍一下自己。

沟通指南#

  • 每一个 PR，无论好坏，都是一种慷慨的行为。以积极的评论开场将有助于作者感到受到认可，并且您随后的意见可能会被更清晰地理解。您自己也可能会感觉良好。

  • 如果可能，从大的问题开始，这样作者就知道他们的意图已被理解。抵制立即逐行审阅或以小型普遍性问题开场的诱惑。

  • 您代表着项目，而 NumPy 很久以前就决定了它将是怎样的项目：开放、富有同情心、欢迎、友好且耐心。对贡献者要友善。

  • 不要让完美成为好的敌人，特别是对于文档而言。如果您发现自己提出了许多小建议，或者对风格或语法过于挑剔，请在所有重要问题都解决后，考虑合并当前的 PR。然后，要么直接提交一个提交（如果您是维护者），要么自己再开启一个后续 PR。

  • 如果您在撰写审阅回复时需要帮助，请查看一些审阅标准回复。

审阅者清单#

  • 在所有条件下，预期行为是否清晰？需要注意的几点：

    • 对于空数组或 nan/inf 值等意外输入会发生什么？

    • 轴或形状参数是否已测试为 int 或 tuples 类型？

    • 如果函数支持不寻常的 dtypes，是否已对其进行测试？

  • 变量名是否应改进以提高清晰度或一致性？

  • 是否应该添加注释，或者移除无用或多余的注释？

  • 文档是否遵循 NumPy 指南？文档字符串是否格式正确？

  • 代码是否遵循 NumPy 的风格指南？

  • 如果您是维护者，并且 PR 描述中不明显，请在合并消息中添加关于分支所做工作的简短解释，如果关闭一个问题，还要添加“Closes gh-123”，其中 123 是问题编号。

  • 对于代码更改，至少一名维护者（即拥有提交权限的人）应审阅并批准拉取请求。如果您是第一个审阅 PR 并批准更改的人，请使用 GitHub 的批准审阅工具进行标记。如果一个 PR 很直接，例如是一个明显正确的错误修复，它可以立即合并。如果它更复杂或更改了公共 API，请将其开放至少几天，以便其他维护者有机会进行审阅。

  • 如果您是对已批准 PR 的后续审阅者，请使用与新 PR 相同的审阅方法（关注更重要的问题，抵制只添加少量细节修改的诱惑）。如果您有提交权限并且认为无需更多审阅，请合并该 PR。

针对维护者#

  • 在合并 PR 之前，请确保所有自动化 CI 测试通过，并且文档构建没有任何错误。

  • 如果出现合并冲突，请要求 PR 提交者在 main 分支上进行 rebase。

  • 对于添加新功能或以某种方式复杂的 PR，请至少等待一两天再合并。这样，在代码提交之前，其他人有机会提出意见。考虑将其添加到发布说明中。

  • 合并贡献时，提交者负责确保其符合 NumPy 开发流程指南中概述的要求。此外，请检查新功能和向后不兼容的更改是否已在 numpy-discussion 邮件列表上进行讨论。

  • 合并提交或清理您认为过于混乱的 PR 提交消息是可以的。请记住在这样做时保留原始作者的姓名。确保提交消息遵循NumPy 规则。

  • 当您想拒绝一个 PR 时：如果非常明显，您可以直接关闭并解释原因。如果不是，那么最好先解释您为什么认为该 PR 不适合包含在 NumPy 中，然后再让第二位提交者评论或关闭。

  • 如果 PR 提交者在 6 个月内没有回复您的评论，请将该 PR 移至非活跃类别，并附加“inactive”标签。此时，该 PR 可以由维护者关闭。如果对正在审议的 PR 有任何兴趣，可以随时通过评论表明，无需等待 6 个月。

  • 当 PR 在合并前只需要少量更改（例如，修复代码风格或语法错误）时，鼓励维护者完成这些 PR。如果一个 PR 变得非活跃，维护者可以进行更大的更改。请记住，PR 是贡献者和审阅者之间的协作，有时直接推动是完成它的最佳方式。

API 更改#

如前所述，大多数公共 API 更改应提前讨论，并通常与更广泛的受众（通过邮件列表，甚至通过 NEP）进行讨论。

对于公共 C-API 的更改，请注意 NumPy C-API 是向后兼容的，因此任何添加都必须与以前的版本 ABI 兼容。如果不兼容，则必须添加一个守卫。

例如，PyUnicodeScalarObject 结构体包含以下内容

#if NPY_FEATURE_VERSION >= NPY_1_20_API_VERSION
    char *buffer_fmt;
#endif

因为 buffer_fmt 字段在 NumPy 1.20 中添加到其末尾（所有之前的字段都保持 ABI 兼容）。同样，添加到 numpy/_core/code_generators/numpy_api.py 中 API 表的任何函数都必须使用 MinVersion 注解。例如

'PyDataMem_SetHandler':                 (304, MinVersion("1.22")),

仅头文件功能（例如新宏）通常不需要受保护。

GitHub 工作流程#

审阅拉取请求时，请酌情使用 GitHub 上的工作流程跟踪功能

  • 完成审阅后，如果您希望提交者进行更改，请将您的审阅状态更改为“需要更改”。这可以在 GitHub 的 PR 页面，“Files changed”选项卡，右上角的“Review changes”按钮处完成。

  • 如果您对当前状态满意，请将拉取请求标记为“已批准”（与“需要更改”的方式相同）。或者（对于维护者）：如果您认为拉取请求已准备好合并，请合并它。

在您自己的机器上签出拉取请求代码的副本可能会很有帮助，以便您可以在本地进行操作。您可以通过单击 PR 页面右上角的 Open with 按钮来使用 GitHub CLI 执行此操作。

假设您已设置好开发环境，您现在可以构建和测试代码了。

审阅标准回复#

将其中一些存储在 GitHub 的已保存回复中可能会有所帮助，以便进行审阅

使用问题
You are asking a usage question. The issue tracker is for bugs and new features.
I'm going to close this issue, feel free to ask for help via our [help channels](https://numpy.com.cn/gethelp/).
欢迎您更新文档
Please feel free to offer a pull request updating the documentation if you feel it could be improved.
自包含的 bug 示例
Please provide a [self-contained example code](https://stackoverflow.com/help/mcve), including imports and data (if possible), so that other contributors can just run it and reproduce your issue.
Ideally your example code should be minimal.
软件版本
To help diagnose your issue, please paste the output of:
```
python -c 'import numpy; print(numpy.version.version)'
```
Thanks.
代码块
Readability can be greatly improved if you [format](https://help.github.com/articles/creating-and-highlighting-code-blocks/) your code snippets and complete error messages appropriately.
You can edit your issue descriptions and comments at any time to improve readability.
This helps maintainers a lot. Thanks!
链接到代码
For clarity's sake, you can link to code like [this](https://help.github.com/articles/creating-a-permanent-link-to-a-code-snippet/).
更好的描述和标题
Please make the title of the PR more descriptive.
The title will become the commit message when this is merged.
You should state what issue (or PR) it fixes/resolves in the description using the syntax described [here](https://githubdocs.cn/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword).
需要回归测试
Please add a [non-regression test](https://en.wikipedia.org/wiki/Non-regression_testing) that would fail at main but pass in this PR.
不要更改不相关的内容
Please do not change unrelated lines. It makes your contribution harder to review and may introduce merge conflicts to other pull requests.