审阅者指南#

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

谁可以成为审阅者？#

审阅可以来自 NumPy 团队以外的人员——我们欢迎领域专家（例如，linalg 或 fft）或项目维护者的贡献。您不必是 NumPy 维护者（拥有合并 PR 权限的 NumPy 团队成员）才能进行审阅。

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

沟通指南#

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

  • 如果可能，请先从大的问题开始，这样作者就会知道他们已经被理解了。抵制立即逐行审阅，或以细小普遍存在的问题开始的诱惑。

  • 您是项目的门面，NumPy 很久以前就决定了项目的类型：开放、有同理心、受欢迎、友好和耐心。请对贡献者友善。

  • 不要让完美成为好的敌人，尤其是在文档方面。如果您发现自己做了很多小的建议，或者对风格或语法过于吹毛求疵，请考虑在所有重要问题都得到解决后合并当前的 PR。然后，要么直接推送一个提交（如果您是维护者），要么自己打开一个后续的 PR。

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

审阅者清单#

  • 在所有条件下，预期行为是否清晰？需要注意的一些事项

    • 当遇到意外输入时，例如空数组或 nan/inf 值，会发生什么？

    • 轴或形状参数是否经过测试为整数或元组？

    • 如果一个函数支持，是否测试了不寻常的dtypes？

  • 变量名是否应该为了清晰或一致性而改进？

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

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

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

  • 如果您是维护者，并且 PR 描述中没有明确说明，请在合并消息中简要说明分支的作用，如果关闭了一个问题，也请添加“Closes gh-123”，其中 123 是问题编号。

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

  • 如果您是已获批准的 PR 的后续审阅者，请使用与新 PR 相同的方法进行审阅（专注于大的问题，抵制只添加少量挑剔意见的诱惑）。如果您有提交权限并认为不再需要审阅，请合并 PR。

对于维护者#

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

  • 如果出现合并冲突，请要求 PR 提交者基于 main 分支重新定序。

  • 对于添加新功能或在某些方面很复杂的 PR，请在合并前至少等待一两天。这样，其他人就有机会在代码被纳入之前发表评论。考虑将其添加到发布说明中。

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

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

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

  • 如果 PR 提交者在 6 个月内未回复您的评论，请将该 PR 移至不活跃类别，并附上“inactive”标签。此时，PR 可以由维护者关闭。如果有兴趣最终确定正在考虑的 PR，可以随时通过评论表明，无需等待 6 个月。

  • 鼓励维护者在只需要进行小的更改（例如，修复代码样式或语法错误）即可合并 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 上的工作流跟踪功能

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

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

将拉取请求的代码检出到您自己的机器上，以便您可以在本地进行操作，这可能会有所帮助。您可以通过单击 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.
错误报告的独立示例
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.