# 版本與相容性

> /v1 中哪些變更不另行通知，哪些會提前 30 天公布，以及在哪裡關注更新。

URL: https://developers.vimine.network/zh-hant/guides/versioning/

API 的版本寫在路徑中（`/v1`），同時還有一個日期：OpenAPI 文件的 `info.version`，即其最近一次變更的日期。每項變更都會在[更新日誌](https://developers.vimine.network/zh-hant/news/)中有對應條目。

## 相容的變更

這類變更在準備就緒後進入 `/v1`，當天即發布對應條目：

- 新的端點、回應中的新欄位、請求中新的選用參數或欄位；
- 參考文件中標明為開放字串的新值（例如 `payment.method`），以及新的錯誤 `code`；
- 新的權限（scope）和新的語言。

為了讓這些變更都不會破壞您的整合：請忽略不認識的欄位，把開放字串中的未知值當作一般情況處理，並為沒有逐一處理的錯誤 `code` 保留一個預設分支。

Vimine 的頁面（登入頁、入會表單、活動行事曆）隨時可能調整外觀；它們的網址和接受的參數遵循與 API 相同的規則。

## 需要您處理的變更

刪除或重新命名欄位、參數改為必填、回應含義改變：這類變更至少提前 **30 天**公布，會發布一則「需處理」條目，說明要改什麼、最晚何時完成，並寄送電子郵件給開發者帳戶以及擁有已啟用應用程式的協會負責人。變更上線時，會再發布一則條目說明。

在測試期內，這類變更進入 `/v1`。測試期結束後，不相容的變更將進入新版本 `/v2`，並與 `/v1` 並行至少六個月。

## SDK 和 WordPress 外掛

- `@vimine/sdk`：在 0.x 版本期間，修補版本（0.3.6）絕不會要求您修改程式碼；次要版本（0.4.0）可能會，其條目會說明要改什麼。這些條目也收錄在套件的 `CHANGELOG.md` 中。
- WordPress 外掛透過 WordPress.org 更新，其外掛頁面列出相同的條目。

## 關注更新

- [更新日誌](https://developers.vimine.network/zh-hant/news/)頁面及其 Atom 訂閱源，提供入口網站的每種語言：繁體中文為 `/zh-hant/news.xml`，義大利語為 `/news.xml`，依此類推。
- 在 Vimine 控制台中，**開發者**頁面會顯示最新條目。
- 「需處理」條目也會透過電子郵件寄送。