贡献 NumPy#

不是程序员？没问题！NumPy 是一个多方面的项目，我们需要很多帮助。以下是我们希望获得帮助的所有活动（它们都很重要，因此我们按字母顺序列出）

  • 代码维护与开发

  • 社区协调

  • DevOps

  • 开发教育内容和叙述性文档

  • 筹款

  • 市场营销

  • 项目管理

  • 内容翻译

  • 网站设计与开发

  • 撰写技术文档

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

  • 在经验丰富的贡献者指导下可以轻松解决（非常适合在冲刺（sprint）中工作）。

  • 对于准备深入学习的人来说是一个学习机会，即使您不在冲刺（sprint）中。

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

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

开发流程 - 摘要#

这是简短的摘要，完整的目录链接在下方

  1. 如果您是首次贡献者

    • 转到 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

  2. 开发您的贡献

    • 为要处理的功能创建一个分支。由于分支名称将显示在合并消息中，请使用有意义的名称，例如“linspace-speedups”

      git checkout -b linspace-speedups

    • 在进展过程中本地提交（git add 和 git commit）。使用正确格式化的提交消息，编写在更改之前失败、更改之后通过的测试，并在本地运行所有测试。确保在文档字符串中记录任何已更改的行为，并遵循 NumPy 文档字符串标准。

  3. 提交您的贡献

    • 将您的更改推回 GitHub 上的 fork。

      git push origin linspace-speedups

    • 转到 GitHub。新分支将显示一个绿色的 Pull Request 按钮。确保标题和消息清晰、简洁且具有自我解释性。然后单击按钮提交。

    • 如果您的提交引入了新功能或更改了功能，请在邮件列表上发布以解释您的更改。对于错误修复、文档更新等，这通常不是必需的，但如果您没有得到任何回应，请随时请求审查。

  4. 审查流程

    • 审稿人（其他开发者和社区感兴趣的成员）将在您的 Pull Request (PR) 上撰写内联和/或通用评论，以帮助您改进其实现、文档和风格。项目中的每一位开发者都会接受代码审查，我们将其视为一次友好的对话，从中我们都可以学习，并使整体代码质量受益。因此，请不要让审查阻碍您贡献：其唯一目的是提高项目质量，而不是批评（毕竟，我们非常感谢您投入的时间！）。有关更多信息，请参阅我们的审稿人指南。

    • 要更新您的 PR，请在您的本地存储库中进行更改、提交、运行测试，并且只有在它们成功后才推送到您的 fork。一旦这些更改被推上去（到与之前相同的分支），PR 将自动更新。如果您不知道如何修复测试失败，您可以先推上去您的更改，然后在 PR 评论中寻求帮助。

    • 每次 PR 更新后，各种持续集成 (CI) 服务都会被触发，以构建代码、运行单元测试、测量代码覆盖率并检查您分支的编码风格。CI 测试必须通过后，您的 PR 才能合并。如果 CI 失败，您可以通过单击“失败”图标（红叉）并检查构建和测试日志来找出原因。为了避免过度使用和浪费此资源，请在提交之前本地测试您的工作。

    • PR 必须由至少一名核心团队成员批准后才能合并。批准意味着核心团队成员已仔细审查了更改，并且 PR 已准备好合并。

  5. 文档更改

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

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

  6. 交叉引用问题

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

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

有关更详细的讨论，请继续阅读并遵循此页面底部的链接。

指南#

  • 所有代码都应有测试（有关更多详细信息，请参阅下面的测试覆盖率）。

  • 所有代码都应记录。

  • 未经核心团队成员审查和批准，任何更改都不得提交。如果您在一周内对您的拉取请求没有收到回复，请在 PR 上或在邮件列表上礼貌地询问。

风格指南#

  • 设置您的编辑器以遵循PEP 8（删除尾随空格、无制表符等）。使用 ruff 检查代码。

  • 使用 NumPy 数据类型而不是字符串（np.uint8 而不是 "uint8"）。

  • 使用以下导入约定

    import numpy as np

  • 对于 C 代码，请参阅NEP 45。

测试覆盖率#

修改代码的拉取请求 (PR) 应包含新测试，或修改现有测试，使其在 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-development-workflow 中。