一組原則會控管與重大變更、通知、發行和版本控制相關的數據 API 產生器。
版本設定和版本
數據 API 產生器內容中的 版本 是指以格式識別 Major.Minor.Patch 之軟體的每個已發佈版本。 這些版本分為三個類別： 穩定、 重大變更和 預覽。
容器更新責任
數據 API 產生器容器不會自動更新。 客戶須負責監視新版本、評估其重要性（包括安全性更新），以及據以更新已部署的容器。
讓容器保持最新狀態是 客戶的責任。
穩定版本
穩定版本的數據 API 產生器回溯相容。 回溯相容表示您撰寫的任何依賴數據 API 產生器版本的程式代碼都可以採用較新的穩定版本，而不需要任何程式碼變更來維護正確性或現有功能。
重大變更版本
數據 API 產生器 的重大變更版本 與回溯相容。 在現有的用戶端程式代碼中採用重大變更版本可能需要變更程式代碼，以確保用戶端在以舊版為目標時的行為完全一樣。
重大變更版本會透過重大變更清單文章和 GitHub 版本的變更描述來宣告。 除非變更修正重大安全性、隱私權或法律問題，否則發行預覽/發行候選版本之前，會先進行重大變更版本。 雖然舊版的數據 API 產生器可能仍可在 GitHub 發行頁面上使用，但建議您升級至最新版本，其中可能包含錯誤修正。
預覽版本
數據 API 產生器預覽版本會以 X.Y.Z-rc 版本設定設定來識別。 後 -rc 綴表示組建是「候選版」。預覽版本可用來收集新功能和其他變更的意見反應。
除非我們打算從最後一個穩定版本進行重大變更，否則我們會發佈下一個預覽版本，其中包含最新穩定版本和新預覽功能的所有專案。 下一個數據 API 產生器更新可能會中斷我們在預覽版本之間新增的一些新的預覽功能。 這種中斷行為表示您可能需要變更程序代碼，才能讓專案再次運作。
預覽版本不適用於長期或生產環境使用。 當新的穩定版本或預覽版本可供使用時，較舊的預覽版本可能無法再存取。 最好只在您主動處理新功能，並準備好在發行后不久切換到非預覽版本時，才使用預覽版本。 如果預覽版本中的某些功能包含在新的穩定版本中，剩餘的預覽功能會新增至新的預覽版本，讓您試用。
版本變更數據表
這很重要
當變更解決重大產品錯誤、法律、安全性或隱私權考慮時，我們可能會對次要或修補程式版本引入重大變更。
| 發行類型 | 舊版 | 新版本 | 註釋 |
|---|---|---|---|
| 重大變更 | 1.Y.Z |
2.Y.Z |
新功能和錯誤修正，以及任何重大變更。 |
| 穩定 | 1.1.Z |
1.2.Z |
除非變更可解決重大產品錯誤、法律、安全性或隱私權問題，否則新功能和錯誤修正，且不會有任何重大變更。 |
| 穩定 | 1.1.1 |
1.1.2 |
除非變更可解決重大產品錯誤、法律、安全性或隱私權考慮，否則沒有新功能或重大變更的錯誤修正。 |
| 預覽 | X.Y.1-rc |
X.Y.2-rc |
新的預覽功能和 Bug 修正。 （如果主要版本顛簸，則會包含重大變更。 |
重大變更
為了排定安全性的優先順序、增強功能及維護程式代碼品質，我們軟體的新版本可能包含重大變更。 雖然我們努力透過仔細的架構選擇將這些變更降到最低，但仍會發生這些變更。 在這種情況下，我們會優先宣佈它們並提供可能的解決方案。
這很重要
如果變更被視為非中斷性，或是要解決重大產品錯誤或法律、安全性或隱私權考慮的重大變更，我們可能會在沒有事先通知的情況下進行變更。
什麼是重大變更？
重大變更是一項修改，要求您更新應用程式以防止中斷。 在數據 API 產生器中，重大變更可能包括變更 REST API 合約、GraphQL 架構產生，以及影響相容性和功能的其他元素。
重大變更範例
下列範例是資料 API 產生器的重大變更 非必要 清單：
- REST API 合約修改
- GraphQL 架構產生中的改變
- 影響回溯相容性的變更
- 拿掉或重新命名 API 或參數
- 錯誤碼中的變更
- 調整許可權定義功能
- 拿掉允許的參數、要求欄位或回應欄位
- 新增必要參數或沒有預設值的要求欄位
- 修改預期的 API 端點功能
非重大變更的定義
非中斷性變更是指可以整合到您應用程式的變更，而不會造成中斷。 非重大變更通常會在實作之後傳達。 您的應用程式應該設計成在不事先通知的情況下處理這些變更。
非重大變更範例
下列範例是數據 API 產生器之非重大變更的非 必要 清單：
- 新端點簡介
- 將方法新增至現有的端點
- 將新欄位納入回應和要求
- 調整回應內的欄位順序
- 選擇性要求標頭的簡介
- 數據長度和回應大小的變更
- 錯誤訊息和代碼的改變
- HTTP 回應碼的修正
- 產生的 OpenAPI 檔中的額外元數據
我們如何溝通重大變更？
我們優先通知您重大變更。 您可以在 GitHub 上的資料 API 產生器版本資訊，以及專用 的重大變更清單一文中找到重大變更通知。
目前的重大變更清單
本文會宣佈重大變更和功能淘汰。
- 截至目前，沒有任何重大變更