[ADP-24] 版本控制機制
簡介
在軟體開發領域中，語義化版本控制（Semantic Versioning，簡稱 SemVer）是一種被廣泛採用的版本控制方案，它提供了明確而簡潔的規則來分配和遞增版本號。本文件概述了在我們的 API 開發和發布過程中遵循語義化版本控制的強制要求。
我們將在 API 設計的不同主題中面臨版本控制，例如 API 版本控制、內容類型版本控制和事件版本控制。
什麼是語義化版本控制？
語義化版本控制（也稱為 SemVer）是一種版本控制系統，旨在傳達發布中底層變更的含義。版本號的格式為 主版本號.次版本號.修訂號，其中：
- 主版本號的變更表示不兼容的 API 變更。
- 次版本號的變更表示以向後兼容的方式添加功能。
- 修訂號的變更表示向後兼容的錯誤修復。
版本格式
版本格式遵循以下模式：主版本號.次版本號.修訂號（例如，1.0.0）。
TIP
💡 在 API 版本控制中，另一種表示版本的方法是使用發布日期。這種方法仍然遵循語義化版本控制原則； 只有主要或次要變更才會影響發布日期。
例如：如果當前版本是 1.0.0，發布於 2024-01-01，並添加了一個向後兼容的功能，新版本可能是 1.1.0，發布日期為 2024-02-15。 對於破壞性變更，版本將是 2.0.0，並附帶相應的發布日期。
指導原則
- 必須(SHOULD)遵循 SemVer：所有版本控制實踐必須(MUST)遵守語義化版本控制（SemVer）。
- 在某些情況下顯示時可以(MAY)忽略修訂號：在某些場景中，可以(MAY)在顯示的版本中省略修訂號，前提是上下文清楚地表明只涉及次要或主要變更。
- 在某些情況下顯示時可以(MAY)忽略修訂號和次版本號：在特定情況下，可以(MAY)在顯示的版本中省略修訂號和次版本號，特別是在傳達主要版本變更時，或當額外的細節對受眾來說不必要時。
實施細節
主版本號遞增
- 當進行不兼容的 API 變更時，必須(MUST)遞增主版本號。
- 不兼容的變更包括移除、重命名或以可能破壞現有客戶端的方式更改現有端點的行為。
- 例如：如果當前版本是
2.4.3，而你引入了一個破壞性變更，新版本將是3.0.0。
次版本號遞增
- 當以向後兼容的方式添加功能時，必須(MUST)遞增次版本號。
- 這包括添加新端點、向現有端點添加新參數（只要它們是可選的），以及任何不破壞現有功能的其他添加。
- 例如：如果當前版本是
2.4.3，而你添加了一個新端點，新版本將是2.5.0。
修訂號遞增
- 當進行向後兼容的錯誤修復時，必須遞增修訂號。
- 錯誤修復包括解決不影響 API 接口或添加新功能的問題，但改善當前版本的穩定性和性能。
- 例如：如果當前版本是
2.4.3，而你修復了一個錯誤，新版本將是2.4.4。 - 根據制定的策略，修訂號的變更可能會被省略。