依赖项指南

本文档描述了保持 Beam 依赖项更新的策略。

过时的依赖项会导致用户痛苦，并可能导致系统对某些用户不可用。许多用户不会孤立地使用 Beam，并且在同一个部署中捆绑其他依赖项。这些额外的依赖项可能会将不兼容的依赖项拉入用户的环境，这可能再次导致 Beam 管道崩溃，有时还伴随未定义的行为。为了防止这种情况，用户必须更新其部署环境，或者更糟糕的是，可能最终无法与其他一些依赖项一起使用 Beam。

Beam Java SDK 的 Gradle 构建定义了一组顶级 依赖项，各种组件（运行器、IO 连接器等）可以选择包含这些依赖项。组件通常使用顶级定义的版本，但可以选择覆盖这些版本。

如果组件 X 选择将依赖项 D 的版本从 a 覆盖到 b，而另一个组件 Y 与 D 的版本 b 不兼容，则使用组件 X 和 Y 的用户的部署将最终处于崩溃状态。

如果 Beam 的两个依赖项依赖于同一个库，但使用该库的不兼容版本，则可能会出现类似的问题。

此外，用户可能不会孤立地使用 Beam，一个依赖于 Beam 以及同一个环境中其他库的用户，如果 Beam 和其他库共享一个依赖项但使用不兼容的版本，可能会遇到类似的问题。

Beam Python SDK 对依赖项的处理方式略有不同，所有依赖项都在单个 setup.py 文件中定义并分组。其中一组描述了必需的依赖项，而其他组用于定义各种可选功能的依赖项。所有 Python 模块都必须使用 setup.py 文件中定义的依赖项版本。此外，对于大多数依赖项，Python SDK 允许自动升级到下一个主要版本。由于这种设置，Python SDK 目前不会遇到组件冲突，但上面描述的其他两种形式的依赖项冲突仍然可能发生。

在运行时，这种情况可能会变得更加复杂。运行器特定代码可能与某些模块包含的依赖项不兼容，如果这些依赖项泄漏到运行时，管道可能最终处于崩溃状态。

总体问题并不局限于 Beam，在业界众所周知，被称为 菱形依赖问题（或依赖地狱）.

解决菱形依赖问题的一个常见方法是 语义版本控制。基本思想是依赖项以 x.y.z 的形式进行版本控制，其中 x 是主版本，y 是次版本，z 是修订版本。主版本更改可能是向后不兼容的，预计这种情况很少发生。次版本和修订版本可能会更频繁地发布，但预计它们是向后兼容的。但在实践中，重要的修复程序（例如安全补丁）可能会以次版本或修订版本更新的形式发布，Beam 项目依赖于最近发布的依赖项的次版本将是有益的。

识别过时的依赖项

保持依赖项更新的一个重要部分包括识别 Beam 的过时依赖项，社区应该尝试升级这些依赖项。

Beam 目前执行每周 Jenkins 作业，该作业尝试识别各种 SDK 的过时依赖项。此 Jenkins 作业会生成每周报告，并在 Beam 开发人员列表中共享。

除了这一点之外，Beam 社区成员可能会识别出其他必须手动执行的关键依赖项更新。例如，

这些紧急需要的升级可能几个月内无法被 Jenkins 作业自动识别。因此，Beam 社区必须采取行动识别这些问题并尽早执行升级。

Dependabot 问题自动化

为了跟踪依赖项升级过程，Dependabot 将自动提出升级过时依赖项的拉取请求。

升级识别出的过时依赖项

识别出过时的依赖项后，Beam 社区必须采取行动定期升级这些依赖项。Beam 社区就升级依赖项达成以下协议：

自动 Jenkins 作业每周生成关于 Beam 依赖项状态的人类可读报告，并通过开发人员列表与 Beam 社区共享。

这些报告应该简洁明了，并应突出显示社区必须采取行动的案例。

Beam 组件应该在顶级定义依赖项及其版本。可能会有很少的例外情况，但它们应该附带说明。

组件包括各种 Beam 运行器、IO 连接器等。组件级依赖项版本声明只应在极少数情况下进行，并且应该附带说明覆盖依赖项原因的注释。例如，特定于运行器并且不太可能被其他组件利用的依赖项可以在运行器中定义。

一个明显过时的依赖项（手动或通过自动 Jenkins 作业识别）应该会导致一个问题，该问题是下一个版本的阻碍。发布经理可以选择将阻碍推迟到后续发布，或将其降级为非阻碍。

这将是 Beam 下一个主要版本和次版本发布的阻碍。

对于手动识别的关键依赖项更新，Beam 社区成员应该为下一个版本创建阻碍性问题。除此之外，Beam 社区成员还可以触发针对任何应该紧急提供给用户的关键依赖项修复的补丁版本发布。

Java SDK 组件的依赖项，如果泄漏可能会导致其他组件出现问题，应该进行捆绑。

捆绑 是创建第三方依赖项副本的过程。与重新打包相结合，捆绑允许 Beam 组件依赖于第三方库，而不会导致其他组件发生冲突。捆绑应该在个别情况下完成，因为这会增加用户环境中部署的依赖项总数。

依赖项更新和向后兼容性

Beam 发布 通常遵循语义版本控制的规则。因此，社区成员在更新依赖项时应该注意。在大多数情况下，对依赖项的次版本更新应该是向后兼容的。但是，对依赖项的一些更新可能会导致 Beam 的 API 或功能发生向后不兼容的更改。PR 审阅者和提交者应该注意检测任何可能在合并之前导致 Beam 发生向后不兼容更改的依赖项更新，更新依赖项的 PR 应该在 PR 评论中包含关于此验证的声明。导致 Beam 非实验性功能发生向后不兼容更改的依赖项更新应该保留到 Beam 的下一个主要版本发布。对该策略的任何例外情况只应在极端情况下发生（例如，由于现有依赖项的安全漏洞，该漏洞只能在后续主要版本中修复），并且应该在 Beam 开发人员列表中进行讨论。请注意，对实验性功能的向后不兼容更改可以在次版本发布中引入。