版本控制系統與儲存庫分支佈局

With the release for beta we’ve moved the SpongeAPI versioning to semantic versioning (see http://semver.org/). This change means that every time that we make a release we have to increment the version according to the rules of semver.

語意化版本(SemVer)

語意化版本(SemVer)使用格式 X.Y.Z,其中 X 是一個主( major)Y是一個次(minor )版號,以及結尾的Z是一個修訂(patch)號。如果釋出內容包含無法向下相容的變更,必須將主(major)版號加一;如果只有新功能卻仍然向下相容,那麼新版本只需將次(minor)版號加一;而如果版本只包含錯誤修正,那麼只需將 修訂(patch)號加一即可。

這就是說,例如 3.2.03.0.0 完全相容,而 4.0.03.0.0 不是二進制相容的。3.1.03.1.2 除了漏洞修復外,完全可以通用。

我們分支佈局(如下所述)是為了簡化此過程,允許我們在沒有重大變化的情況下只發佈次要版本,而不需迫使我們發佈主要版本。此分支佈局適用於 SpongeAPI、SpongeCommon、SpongeForge 和 SpongeVanilla 儲存庫,但不適用於 SpongeDocs。

SpongeAPI、SpongeCommon、SpongeForge 與 SpongeVanilla

不穩定分支(Bleeding Branch)

我們儲存庫的核心是 bleeding 分支。幾乎所有的更改都將被添加到 bleeding,包括新功能、更改和錯誤修復。Bleeding 的將以下一個主版號加上 -SNAPSHOT(例如 6.0.0-SNAPSHOT)作為版本號,以表示它還不是最終版本,並且可能還會有更改。

設立 bleeding 分支的主要原因是為了測試更改。即使有經驗的 Sponge 團隊成員也可能意外地導致建置失敗或錯過一個錯誤。Bleeding 分支將由社群中需要最新版的人員來進行測試,這意味著我們可以更容易修復出現的錯誤。

穩定分支(Stable Branch)

穩定分支讓用於建置插件與伺服器實作的平台更加穩定。API 將不會出錯,只有非破壞性的添加。每當 API 迎來一次主要版本更新後,將多出一個對應的穩定分支,其涵蓋了最新的 API 與實作,以及次要更新或修訂的釋出。

即將發佈一個主要版本時,會從 bleeding 中建立一個新的 stable-x 分支,其中 x 為新的主要版本——例如 stable-5 。如上所述, bleeding 將被妥善地更新為下一個主要版本。

已經存在於 bleeding 一段時間的變更,沒有已知的漏洞,並能適用於以前的主要版本,會被挑選為未來的 stable 分支。除非是即將被建立為漏洞修復版本的即時性變更,否則多數改動都會被分類為次要版本。當版本發佈時,API 儲存庫會為版本的提交建立一個標籤。

特性分支(Feature Branch)

新功能或更動應建立於 feature/foofix/bar 分支。應基於 bleeding 最近的提交。唯一的例外是這些修改更無法相容於 bleeding 的重大變更,這種情況下則應該基於 stable-x 版本。你應該在你的 Pull Request 中說明為何你的更動無法放入 bleeding ——例如修正未來版本中被 Mojang 移除的特性。

如果所做的變更與先前版本差異不大,Sponge 團隊也會從已合併到 bleeding 的變更中挑選出沒有問題的一個或多個變更放入 stable 分支。

SpongeDocs

SpongeDocs 本身沒有版本號。我們相信它們永遠不會完成,因不斷新增的可用性而不斷變化。然而,他們是有目標地針對某特定版本的 API,通常是最新的發行版的 SpongeAPI。

核心分支(Core Branch)

SpongeDocs 的核心分支為 master 。新提交到 master 的每個 commit 都會觸發 docs website 的重建。 master 上的提交一般而言是用來讓文件符合最新的 SpongeAPI 版本或是修復 Docs 上的小錯誤。

特性分支(Feature Branch)

不論是描述一個新的特徵,還是舊文本被更新或重新編寫,或者文件被重新構建,這都是在一個 feature/foofix/bar 分支中完成的。這些分支將被審查,一旦認定完成,就可能會被合併。

如果更改/添加對於當前 SpongeDocs 所指向的 SpongeAPI 發佈版是正確的,則可以將功能分支合併到主分支中。任何描述尚未包含在發行版中的新功能,都會在功能分支保持未發佈狀態,直到相應的 API 版本發佈,並成為 SpongeDocs 的新目標版本。當然,文件團隊可能會為某個版本收集新內容到一個獨立的分支上去。

release branch example

發行分支(Release Branch)

SpongeDocs 使用 release/x.y.z 分支為 API 3.1.0 等較舊的 API 版本發佈文件。較舊的 API 版本可在各自的分支上取得。每當發佈一個新的 API 版本時,Docs Staff 將在之後建立一個新的 release/x.y.z 分支,並將主分支調到新的 API 版本。release 分支的提交也會觸發舊版 Docs 版本的重建,就像核心分支一樣。