跳到内容

贡献

贡献

一般准则

sparse 是 GitHub 上的一个社区驱动项目。您可以在 GitHub 上找到我们的仓库。欢迎就新功能或错误提出问题，或提交拉取请求以修复错误或添加新功能。

如果您以前从未参与过开源项目，我们建议您阅读 GitHub 提供的这份关于如何参与开源的优秀指南。该指南内容很长，您可以略过您熟悉的部分。

如果您还不熟悉，我们在 GitHub 上遵循分支与拉取（fork and pull）模型。

提交问题

如果您发现错误或希望新增功能，您可能需要考虑在 GitHub 上提交一个新问题。在您提出新问题之前，请确保以下几点：

  • 这不言而喻，但请确保您请求的内容在此项目范围内。
  • 该错误/功能在 GitHub 的 main 分支上仍然存在/缺失。
  • 没有类似的问题或拉取请求已经开放。如果已经有，最好在那里参与讨论。

贡献代码

本项目对所有贡献的代码都有一些要求。

  • 我们使用 pre-commit 自动检查代码风格并维护代码格式。
  • 我们使用 Numpy 风格的文档字符串。
  • 用户可见的 API 更改或新功能最好能添加文档。
  • 任何提交的 PR 中的所有新代码都建议达到 100% 的代码覆盖率。Doctest 也计入覆盖率。
  • 性能优化应该在 benchmarks 中添加基准测试。

设置开发环境

在您派生并克隆仓库后，您只需要运行以下 bash 脚本即可设置您的开发环境

pip install -e .[all]

拉取请求

请遵守以下准则

  1. 您的拉取请求标题应以规范化提交（conventional commit）标签开头。这有助于我们将您的贡献添加到更新日志的正确部分。我们使用 Angular 规范中的“类型”。
    简而言之
    拉取请求标题应以以下任一缩写开头：build, chore, ci, depr, docs, feat, fix, perf, refactor, release, test。如果是破坏性更改，请在末尾添加一个 !。例如 refactor!。
  2. 此文本将最终出现在更新日志中。
  3. 请按照拉取请求表单中的说明进行操作并提交。

运行/添加单元测试

所有新功能和/或错误修复最好都能针对每个用例添加单元测试。

我们使用 pytest 作为我们的单元测试框架，并使用 pytest-cov 扩展来检查代码覆盖率，使用 pytest-flake8 来检查代码风格。您无需自行配置这些扩展。配置好环境后，您只需 cd 到仓库根目录并运行

pytest --pyargs sparse

这会自动检查代码风格和功能，并打印代码覆盖率，尽管它不会因低覆盖率而失败。

单元测试会自动在 Travis CI 上为拉取请求运行。

高级

要运行针对您平台的 CI 中的完整单元测试集，请在仓库根目录中运行以下命令

ci/setup_env.sh
ACTIVATE_VENV=1 ci/test_all.sh

覆盖率

pytest 脚本会自动报告覆盖率，包括在终端显示缺失行号，以及在 htmlcov/index.html 中以带注解的 HTML 格式显示。

拉取请求的覆盖率会自动在 CodeCov 上检查。

添加/构建文档

如果一个功能稳定且相对最终化，是时候将其添加到文档中了。如果您正在添加任何私有/公共函数，最好添加文档字符串（docstrings），以帮助代码审查和生成 API 参考。

我们使用 Numpy 风格的文档字符串 和 MkDocs Material 主题 来编写本库的文档。MkDocs 则使用 Markdown 作为其标记语言来添加代码。

我们使用 mkdocstrings 配合 mkdocs-gen-files 插件 来生成 API 参考文档。

要构建文档，您可以运行

mkdocs build
mkdocs serve

在此之后，您可以在本地服务器上查看文档版本。

每个拉取请求的文档都会在 Read the Docs 上自动构建。每次您对拉取请求进行新的提交时，文档都会重新构建。准备就绪后，在 GitHub 上的拉取请求检查区域会提供一个预览链接。

添加和运行基准测试

我们使用 CodSpeed 来运行基准测试。当拉取请求被打开时，它们会在 CI 环境中运行。然后运行结果会发送到 CodSpeed 服务器进行分析。分析完成后，会自动生成一份报告并作为评论发布到拉取请求。报告中包含一个指向 CodSpeed 云的链接，您可以在其中查看所有结果。

如果您添加基准测试，它们应该作为常规测试编写，与 pytest 一起使用，并使用 benchmark fixture。更多详情请参阅 CodSpeed 文档。