相依性指南

本文檔描述了保持 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 社群已就升級相依性達成以下政策。

Beam 相依性的狀態的人類可讀報告由自動化的 Jenkins 作業每週產生，並透過開發人員清單與 Beam 社群分享。

這些報告應簡潔扼要，並應重點說明社群必須採取行動的情況。

Beam 元件應在頂層定義相依性及其版本。可能會有極少的例外情況，但應附有解釋。

元件包含各種 Beam 執行器、IO 連接器等。只有在極少數情況下才應執行元件層級的相依性版本宣告，並且應附有註解，說明覆寫相依性的原因。例如，特定於執行器且不太可能被其他元件使用的相依性可能會在執行器中定義。

明顯過時的相依性（手動識別或透過自動化的 Jenkins 作業識別）應導致一個問題，該問題是下一個發佈的阻礙。發佈管理員可以選擇將阻礙推遲到後續發佈或從阻礙降級。

這將是 Beam 下一個主要版本和次要版本發佈的阻礙。

對於手動識別的重大相依性更新，Beam 社群成員應為下一個發佈建立封鎖問題。除此之外，Beam 社群成員可能會觸發任何重大相依性修正的修補程式發佈，這些修復程式應立即提供給使用者。

如果洩漏，可能會導致其他元件出現問題的 Java SDK 元件的相依性應該是供應商提供的。

供應商是建立第三方相依性副本的過程。結合重新封裝，供應商允許 Beam 元件依賴第三方程式庫，而不會導致其他元件發生衝突。應根據具體情況進行供應商，因為這可能會增加使用者環境中部署的相依性總數。

相依性更新與向後相容性

Beam 發佈通常遵循語意版本控制的規則。因此，社群成員在更新相依性時應小心。相依性的次要版本更新在大多數情況下應該是向後相容的。但是，對相依性的一些更新可能會導致 Beam 的 API 或功能變更不向後相容。PR 審閱者和提交者應注意檢測任何可能在合併之前對 Beam 引入不向後相容變更的相依性更新，並且更新相依性的 PR 應以 PR 註解的形式包含有關此驗證的聲明。對 Beam 非實驗性功能產生不向後相容變更的相依性更新應保留到 Beam 的下一個主要版本發佈。此政策的任何例外情況都應僅在極端情況下發生（例如，由於現有相依性的安全性漏洞僅在後續主要版本中修復），並且應在 Beam 開發人員清單中討論。請注意，對實驗性功能的不向後相容變更可能會在次要版本發佈中引入。