为 NumPy 做贡献#

不是程序员?没问题!NumPy 是多方面的,我们有很多地方需要帮助.这些都是我们希望得到帮助的活动（它们都非常重要,所以我们按字母顺序列出）:

  • 代码维护和开发

  • 社区协调

  • DevOps

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

  • 筹款

  • 营销

  • 项目管理

  • 翻译内容

  • 网站设计和开发

  • 编写技术文档

本文档的其余部分讨论了在 NumPy 代码库和文档上的工作.我们正在更新对其他活动和角色的描述.如果您对这些其他活动感兴趣,请与我们联系!您可以通过 numpy-discussion 邮件列表 或 GitHub <https://github.com/numpy/numpy>`__（打开一个问题或评论一个相关问题）来完成此操作.这些是我们首选的沟通渠道（开源本质上是开放的!）,然而,如果您更愿意首先在更私密的空间讨论,您可以在 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,指的是你的个人分支

    • 从上游拉取最新的更改,包括标签:

      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 上的分支:

      git push origin linspace-speedups

    • 前往 GitHub.新分支将显示一个绿色的 Pull Request 按钮.确保标题和消息清晰、简洁且自明.然后点击按钮提交.

    • 如果你的提交引入了新功能或更改了功能,请在 邮件列表 上解释你的更改.对于错误修复、文档更新等,通常不需要这样做,但如果你没有得到任何反应,请随时要求审查.

  4. 评审过程:

    • 评审者（其他开发者和感兴趣的社区成员）会在你的 Pull Request (PR) 上写入行内和/或一般性评论,以帮助你改进其实现、文档和风格.每个参与项目的开发者都会被评审其代码,我们将其视为一种友好的对话,从中我们都能学习并且整体代码质量受益.因此,请不要让评审打击你贡献的积极性:其唯一目的是提高项目质量,而不是批评（毕竟,我们非常感谢你捐赠的时间!）.更多信息请参见我们的 评审者指南.

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

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

    • 在合并之前,PR 必须至少由一名核心团队成员 批准.批准意味着核心团队成员已经仔细审查了更改,并且 PR 已准备好合并.

  5. 文档更改

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

    如果你的更改引入了弃用,请务必首先在GitHub或邮件列表上讨论这一点.如果就弃用达成一致,请遵循 NEP 23弃用政策 添加弃用.

  6. 交叉引用问题

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

    在源代码中,请确保在任何问题或PR引用前加上 gh-xxxx.

欲了解更多详细讨论,请继续阅读并跟随本页面底部的链接.

准则#

  • 所有代码都应该有测试（详见下面的 测试覆盖率）.

  • 所有代码都应 记录.

  • 没有核心团队成员的审查和批准,任何更改都不会被提交.如果在提交拉取请求一周后没有得到回应,请礼貌地在 PR 或 邮件列表 上询问.

风格指南#

  • 设置你的编辑器以遵循 PEP 8 （移除尾随空白,不使用制表符等）.使用 pyflakes / flake8 检查代码.

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

  • 使用以下导入约定:

    import numpy as np

  • 对于C代码,请参见 NEP 45.

测试覆盖率#

修改代码的拉取请求（PRs）应该有新的测试,或者修改现有测试,使其在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-开发流程.

On this page