跳至主要內容

發佈流程

讓我們了解 Docusaurus 如何處理版本化、發布和重大變更。

資訊

對於可能在升級時遇到困難的高度自訂網站來說，這個主題尤其重要。

語義化版本​

Docusaurus 版本化基於主版本號.次版本號.修訂號方案，遵循 語義化版本。

遵循語義化版本有以下多種原因：

  • 它保證簡單的次要版本升級，只要您僅使用公開 API。
  • 它遵循前端生態系統慣例
  • 新的主版本是徹底記錄重大變更的機會
  • 新的主版本/次要版本是透過部落格文章傳達新功能的機會
註解

Docusaurus 2.0 發行花費了很長的時間。從現在開始，Docusaurus 將更定期地發行主要的新版本。實際上，你可以在每 2-4 個月預期會有新主要版本。

主要版本號並不神聖，但我們仍將重大變更分組處理，並避免太頻繁地發布主要版本。

主要版本​

major 版本號在每次重大變更時遞增。

每當發布新的主要版本，我們將發布以下內容

  • 一篇部落格文章，包含功能重點、重大錯誤修復、重大變更和升級說明。
  • 一份詳盡的變更記錄條目
秘訣

閱讀我們的 公共 API 介面 章節，以便清楚了解我們將什麼視為重大變更。

次要版本​

minor 版本號在每次重要的向下相容變更時遞增。

每當發布新的次要版本，我們將發布以下內容

  • 一篇部落格文章，包含功能重點清單和重大錯誤修復
  • 一份詳盡的變更記錄條目
秘訣

如果你只使用我們的 公共 API 介面，你應該可以在短時間內完成升級！

修補版本​

patch 版本號在錯誤修復時遞增。

每當發布新的修補版本，我們將發布以下內容

  • 一份詳盡的變更記錄條目

版本​

Docusaurus 團隊通常同時開發 2 個主要版本

  • Docusaurus 2：穩定版本，在 docusaurus-v2 分支上
  • Docusaurus 3：下一個版本，位於 main 分支上
註解

在發布第一個 v2 發行候選版本之前建立 docusaurus-v2 分支。

穩定版本​

推薦大多數 Docusaurus 使用者使用穩定版本 (v2，位於 docusaurus-v2)。

我們會定期將 main 的向後相容功能、錯誤修正和安全修正回傳至 docusaurus-v2，使用 git cherry-pick 讓尚未準備好使用下一個版本的使用者也能使用這些功能。

資訊

在新穩定版本發布後，前任穩定版本將只會繼續在3 個月內提供重大安全問題的支援。除此之外，所有功能都將凍結，而且不會修正非重大錯誤。

建議在那段時間內升級至新的穩定版本。

下一個版本​

下一個版本 (v3，位於 main) 是 Docusaurus 團隊目前正在開發的版本。

main 分支是所有提交請求的預設目標分支，包括核心團隊和外部貢獻。

對於希望盡早使用最新 Docusaurus 功能的早期使用者而言，推薦使用此版本。這是透過回報錯誤和提供回饋來協助我們的好方法。

有 3 個使用下一個版本的方法

  • 使用 alpha、beta 或 rc 預發行版本
  • 使用最新的預發行版本之 @next npm dist 標籤
  • 使用 金絲雀發行版本 以存取最新功能
秘訣

下一個版本已通過所有自動化測試，且 Docusaurus 網站本身使用此版本。其相對安全：請不要害怕嘗試看看。

警告

下一個版本可能會發生重大變更：變更紀錄和提交請求中提供詳細的升級說明。

在beta 和 rc (發行候選) 階段，我們避免引入重大的重大變更。

公開 API 範圍​

Docusaurus 承諾遵守語意化版本管理。這表示，每當 Docusaurus 公開 API 發生變更，且破壞向後相容性時，我們會增加 major 版本號碼。

秘訣

Docusaurus 保證公開 API 的向後相容性橫跨 minor 版本。除非您使用內部 API，否則應易於升級 minor 版本。

我們將概述哪些內容算作公開 API 範圍。

核心公開 API​

✅ 我們的公開 API 包括

  • Docusaurus 設定檔
  • Docusaurus 伺服端 API
  • Docusaurus CLI
  • 預設選項
  • 外掛程式選項
  • 外掛程式生命週期 API
  • 主題設定檔
  • 核心外掛程式路由元件屬性
  • @docusaurus/types TypeScript 類型
    • 我們仍保有收緊類型（可能會中斷類型檢查）的彈性。

❌ 我們的公開 API 不包含

  • Docusaurus 設定檔 future
  • 所有標示為 experimental_ 或 unstable_ 的功能
  • 所有標示為 v<MajorVersion>_（v6_ v7_ 等）的功能
秘訣

非主題 API 中，任何文件化的 API 都視為公開（且穩定）；任何未記錄的 API 都視為內部。

API 的「穩定」表示，如果您在不進行任何其他變更的情況下增加您的 Docusaurus 安裝的修補或次要版本，執行 docusaurus start 或 docusaurus build 不應擲回錯誤。

主題公開 API​

Docusaurus 有一個非常靈活的主題系統

  • 您可以使用自訂 CSS
  • 您可以調整任何 React 主題元件

此系統也隱含建立非常大的 API 範圍。為了能夠快速進行變更和改善 Docusaurus，我們無法保證向後相容性。

✅ 我們的公開主題 API 包括

秘訣

您無法透過此公開 API 來達成您的網站自訂化。

因此，請回報您的自訂化使用案例，我們會找出擴充公開 API 的方法。

❌ 我們的公開主題 API 不包含

  • DOM 結構
  • 具有雜湊字尾的 CSS 模組類別名稱（通常採用 [class*='myClassName'] 選擇器為目標）
  • React 元件，其中無法調整或禁止調整
  • 從 @docusaurus/theme-common/internal 匯入的 React 元件
  • 主題的精確視覺外觀
註解

執行元件的安全切換時，您可能會遇到從 @docusaurus/theme-common 匯入未記錄 API（不含 /internal 子路徑）的元件。

我們仍對這些 API 保持向後相容性（因此標記為「安全」），但我們不建議直接使用。

編輯此頁面
最後更新時間由 Sébastien Lorber 在 更新。