为 NumPy 贡献代码#

不会编程？没问题！NumPy 多方面发展，我们非常需要您的帮助。以下是一些我们希望得到帮助的活动（所有活动都很重要，因此我们按字母顺序列出）

  • 代码维护和开发

  • 社区协调

  • DevOps

  • 开发教育内容和叙事文档

  • 筹款

  • 市场营销

  • 项目管理

  • 翻译内容

  • 网站设计和开发

  • 撰写技术文档

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

开发流程 - 摘要#

以下是简短摘要，完整的 TOC 链接在下方

  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 接受的其他任何类型github accepts。

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

有关更详细的讨论，请继续阅读并关注本页底部的链接。

指南#

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

  • 所有代码都应有文档。

  • 在没有核心团队成员审查和批准的情况下，绝不会提交任何更改。如果您在一周内没有收到对您的 pull request 的任何回复，请礼貌地在 PR 或邮件列表上询问。

样式指南#

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

  • 使用 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-development-workflow 中。

本页内容