持续集成#

持续集成 (CI) 是我们开发过程的一部分，旨在确保贡献给 SciPy 的每一段代码或文档都能正常工作，且不会产生预料之外的影响。

注意

在提交或更新您的 PR 之前，请确保您已在本地测试了更改。请参阅 提交 PR 前的检查清单 和 在本地运行 SciPy 测试。

工作流#

我们运行 20 多个不同的工作流，涵盖了不同版本的依赖项、不同的架构等。PR 必须通过所有这些检查才能被合并，以确保项目的可持续状态。

除了单元测试，文档和文档字符串（docstrings）中的示例也会被检查。由于 Sphinx 和 doctest 的规则非常严格，这些工作流经常会出现失败。这些方面非常重要，因为文档和示例是面向用户的元素。确保这些元素能被正确渲染。

日志可能很长，但您总能找到构建/测试未通过检查的原因。只需点击 Details 即可访问日志。

以下是目前使用的所有不同工作流的列表。它们按 CI 资源提供商进行分组。

GitHub Actions#

  • Lint：PEP8 和代码风格检查

  • Windows Tests：Windows 平台下的测试套件运行

  • Linux Tests：Linux 平台下的测试套件运行

  • macOS Tests：macOS (x86_64) 平台下的测试套件运行

  • Wheels builder：为 SciPy 发布版本以及每日构建（nightly）版本构建 wheel 文件。

  • Check the rendered docs here!：文档的实时预览

  • prerelease_deps_coverage_64bit_blas：使用依赖项的预发布版本并检查代码覆盖率

  • gcc-9：使用支持的最低 GCC 版本进行构建，安装 wheel，然后使用 python -OO 运行测试套件

  • Array API：测试 Array API 支持情况

在 GitHub Actions 和其他平台上运行的测试套件涵盖了一系列测试/环境条件：Python 和 NumPy 版本（从最低支持版本到每日构建版本）、32 位 vs. 64 位、不同的编译器等等——详情请参阅 .yml 配置文件。

CircleCI#

  • build_docs：构建文档

  • build_scipy

  • run_benchmarks：验证更改对性能的影响

  • refguide_check：检查来自示例和基准测试的 doctests

跳过检查#

作为一个开源项目，我们可以使用一定配额的 CI 资源。归根结底，资源是有限的，我们应该谨慎使用。这就是为什么我们要求您在推送更改之前先在本地进行验证。

根据提议的更改，您可能希望跳过部分检查。维护者将自行决定在集成前是否重新运行某些测试。

可以通过在提交信息中添加特定文本来跳过 CI：

  • [skip actions]：将跳过 GitHub Actions

  • [skip circle]：将跳过 CircleCI

  • [docs only]：将跳过除 CircleCI 检查和 linter 之外的所有内容

  • [lint only]：将跳过除 linter 之外的所有内容

  • [skip ci]：将跳过所有 CI 检查

当然，您可以组合这些标签来跳过多个工作流。

这些跳过信息应另起一行。在这个例子中，我们刚刚更新了文档中的一个 .rst 文件，并要求跳过除相关文档检查之外的所有内容（即跳过 GitHub Actions 的工作流）：

DOC: improve QMCEngine examples.

[docs only]

因测试超时导致的失败#

某些 CI 任务安装了 pytest-fail-slow，当测试执行时间超过阈值时长时会报告失败。

  • 默认情况下，所有测试都受到 5 秒的限制；即在“完整（full）”测试任务中使用 --fail-slow=5.0 选项。

  • 所有未标记为 slow (@pytest.mark.slow) 的测试都受到 1 秒的限制；即在“快速（fast）”测试任务中使用 --fail-slow=1.0 选项。

  • 可以使用 pytest.mark.fail_slow 装饰器设置例外；例如，一个测试可以被标记为 @pytest.mark.fail_slow(10)，无论它是属于“快速”还是“完整”测试套件，都会给予其 10 秒的限制。

如果在 PR 开发过程中的任何阶段，测试因超过时限而失败，请调整该测试以确保将来不再失败。即使新测试没有失败，也请在 PR 合并前检查名称中包含“fail slow”的工作流详情。这些详情列出了接近（或已超过）时限的测试。由于执行时间存在波动，对于执行时间接近阈值的测试应进行调整，以确保即使执行时间增加 50% 也不会失败；典型的测试应留有更大的余地（至少 400%）。调整选项包括：

  • 提高测试速度。

  • 如果可以在减少的平台集中运行该测试，则将其标记为 slow。

  • 如果可以接受仅偶尔运行该测试，则将其标记为 xslow。

  • 拆分测试或对其进行参数化，并可能将其中一部分标记为 slow。请注意，这并不会减少总测试时长，因此优先考虑其他选项。

  • 对于确实关键且无法避免耗时的测试，使用 pytest.mark.fail_slow 添加例外。

有关在本地处理慢速测试的更多信息，请参阅 在本地运行 SciPy 测试。

Wheel 构建#

用于 SciPy 发布版本和 *每日构建* 的 wheel 文件是使用 cibuildwheel 在 Github Action 中构建的。该 Action 在以下情况下运行：

  • 当提交信息包含文本 [wheel build] 时

  • 每周一次的定期计划

  • 手动启动时

  • 当向仓库推送 GitHub 引用以 refs/tags/v 开头（且不以 dev0 结尾）的标签时

该 Action 不会在主 SciPy 仓库的分支（forks）上运行。创建的 wheel 文件作为成功运行 Action 的相关产物（artifacts）提供。当 Action 按计划运行或手动启动时，wheel 文件会被上传到 *scientific-python-nightly-wheels* 仓库。

不建议在您自己的系统上使用 cibuildwheel 来构建 scipy wheel，因为它会自动安装 gfortran 编译器和各种其他依赖项。相反，您可以使用隔离的 Docker 容器来构建 Linux wheel。