持续集成#

持续集成 (CI) 是我们开发流程的一部分,它确保每个贡献给 SciPy 的代码或文档都能正常工作,并且不会产生无法预见的影响。

注意

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

工作流程#

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

除了单元测试之外,还会检查文档字符串中的文档和示例。这些都是常见的失败工作流程,因为 Sphinx 和 doctest 有非常严格的规则。这些方面非常重要,因为文档和示例是面向用户的元素。确保这些元素正确呈现。

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

以下是正在使用的所有不同工作流程的列表。它们按 CI 资源提供商分组。

GitHub Actions#

  • Lint:PEP8 和代码风格

  • Windows Tests:Windows 的测试套件运行

  • Linux Tests:Linux 的测试套件运行

  • macOS Tests:macOS 的测试套件运行 (x86_64)

  • Wheels builder:为 SciPy 版本以及每日构建构建 wheels。

  • 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 位与 64 位、不同的编译器等等 - 有关详细信息,请参阅 .yml 配置文件。

CircleCI#

  • build_docs:构建文档

  • build_scipy

  • run_benchmarks:验证更改如何影响性能

  • refguide_check:来自示例和基准测试的 doctest

跳过#

作为一个开源项目,我们可以访问 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 秒限制;即,在“完整”测试作业中使用选项 --fail-slow=5.0

  • 所有未标记为 slow (@pytest.mark.slow) 的测试都受 1 秒限制;即,在“快速”测试作业中使用选项 --fail-slow=1.0

  • 使用 pytest.mark.fail_slow 装饰器进行例外处理;例如,可以将测试标记为 @pytest.mark.fail_slow(10),无论它是“快速”还是“完整”测试套件的一部分,都为其提供 10 秒的限制。

如果在 PR 的开发过程中,测试因超过时间限制而失败,请调整测试以确保将来不会失败。即使新测试没有失败,请在 PR 合并之前检查包含名称中包含“fail slow”的工作流程的详细信息。这些包括接近(或已经超过)其时间限制的测试列表。由于执行时间的差异,应调整执行时间接近阈值的测试以避免失败,即使它们的执行时间增加 50%;典型测试应具有更大的余量(至少 400%)。调整选项包括

  • 使测试更快。

  • 如果可以接受在减少的平台上运行测试,则将测试标记为 slow

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

  • 分解测试或参数化它,并可能将其部分标记为慢速。请注意,这不会减少总测试持续时间,因此首选其他选项。

  • 对于真正关键但不可避免的慢速测试,请使用 pytest.mark.fail_slow 添加例外。

有关在本地使用慢速测试的更多信息,请参阅在本地运行 SciPy 测试

Wheel 构建#

SciPy 版本和 *每日* 构建的 Wheels 是使用 cibuildwheel 在 Github Action 中构建的。该 Action 运行

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

  • 每周一次定期

  • 手动启动时。

  • 当推送到存储库时,GitHub 引用以 refs/tags/v 开头(不以 dev0 结尾)

该 Action 不在 SciPy 主存储库的分支上运行。创建的 wheels 可用作与 Action 成功运行相关的工件。当 Action 按计划运行或手动启动时,wheels 会上传到 *scientific-python-nightly-wheels* 存储库。

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