Skip to main content

发布流程

让我们看看Docusaurus如何处理版本控制、发布和重大变更。

info

对于可能难以升级的高度定制化站点，此主题尤为重要。

语义版本控制​

Docusaurus 版本控制基于 major.minor.patch 方案，并遵循 语义化版本控制。

尊重语义版本控制对于多种原因很重要：

  • 它保证简单的次要版本升级，只要您仅使用公共API
  • 它遵循前端生态系统的惯例
  • 新的大版本是彻底记录重大变更的机会
  • 新的主要/次要版本是通过博客文章传达新功能的机会
note

发布Docusaurus 2.0花了很长时间。从现在开始，Docusaurus将更定期地发布新的主要版本。实际上，您可以预期每2-4个月就会有一个新的主要版本。

主要版本号并不神圣，但我们仍然会将重大更改集中在一起，并避免过于频繁地发布主要版本。

主要版本​

major 版本号在每次重大变更时递增。

每当发布新的主要版本时，我们会发布：

  • 一篇博客文章，包含功能亮点、主要错误修复、重大更改和升级说明。
  • 详尽的变更日志条目
tip

阅读我们的公共API表面部分，以清楚地了解我们认为什么是破坏性更改。

次要版本​

minor 版本号在每次重要的向后兼容更改时递增。

每当发布新的次要版本时，我们会发布：

  • 一篇博客文章，包含功能亮点和主要错误修复的列表
  • 详尽的变更日志条目
tip

如果您只使用我们的公共API接口，您应该能够很快升级！

补丁版本​

patch 版本号在错误修复发布时递增。

每当发布新的补丁版本时，我们会发布：

  • 详尽的变更日志条目

版本​

Docusaurus 团队通常同时开发两个主要版本：

  • Docusaurus 2: 稳定版本，位于docusaurus-v2分支
  • Docusaurus 3: 下一个版本，在 main 分支上
note

docusaurus-v2 分支是在发布第一个 v2 发布候选版本之前创建的。

稳定版本​

对于大多数Docusaurus用户来说，推荐使用稳定版本（v2，在docusaurus-v2上）。

我们定期将向后兼容的功能、错误和安全修复从main回溯到docusaurus-v2，使用git cherry-pick使那些尚未准备好升级到下一个版本的用户也能使用这些更新。

info

在新稳定版本发布后，前一个稳定版本将仅继续接收重大安全问题的支持，持续3个月。除此之外，所有功能将被冻结，非关键性错误将不会被修复。

建议在该时间范围内升级到新的稳定版本。

下一个版本​

下一个版本（v3，在main上）是Docusaurus团队目前正在开发的版本。

main 分支是所有拉取请求的默认目标分支，包括核心团队和外部贡献。

此版本推荐给希望尽快使用最新Docusaurus功能的早期采用者。这也是通过报告错误和提供反馈来帮助我们的好方法。

有三种方法可以使用下一个版本：

  • 带有 alpha、beta 或 rc 预发布版本
  • 使用@next npm dist标签获取最新的预发布版本
  • 使用金丝雀发布来获取最新功能
tip

下一个版本通过了我们所有的自动化测试，并且被Docusaurus网站本身使用。它相对安全：不要害怕尝试。

warning

下一个版本可能会发生重大变化：详细的升级说明可在变更日志和拉取请求中找到。

在beta和rc（发布候选）阶段，我们避免引入重大的破坏性更改。

公共API接口​

Docusaurus 承诺遵循语义化版本控制。这意味着每当 Docusaurus 的公共 API 发生变化并破坏向后兼容性时，我们将增加 major 版本号。

tip

Docusaurus 保证在 minor 版本之间的公共 API 向后兼容。除非你使用内部 API，否则 minor 版本升级应该是容易的。

我们将概述哪些内容被视为公共API表面。

核心公共API​

✅ 我们的公共API包括：

  • Docusaurus 配置
  • Docusaurus 客户端 API
  • Docusaurus 命令行界面
  • 预设选项
  • 插件选项
  • 插件生命周期API
  • 主题配置
  • 核心插件路由组件属性
  • @docusaurus/types TypeScript 类型
    • 我们仍然保留使类型更严格（可能会破坏类型检查）的自由。

❌ 我们的公共API 不包括:

  • Docusaurus 配置 future
  • 所有以experimental_或unstable_为前缀的功能
  • 所有以v_为前缀的功能（v6_ v7_等）
tip

对于非主题API，任何有文档记录的API都被视为公开的（并且将是稳定的）；任何没有文档记录的API都被视为内部的。

API 的“稳定”意味着如果你在没有任何其他更改的情况下增加 Docusaurus 安装的补丁或次要版本，运行 docusaurus start 或 docusaurus build 不应该抛出错误。

主题公共API​

Docusaurus 拥有一个非常灵活的主题系统：

  • 您可以使用自定义CSS
  • 你可以swizzle任何React主题组件

该系统还隐式创建了一个非常大的API接口。为了能够快速行动并改进Docusaurus，我们无法保证向后兼容性。

✅ 我们的公共主题API包括：

tip

您可能无法通过此公共API实现您的站点定制。

在这种情况下，请报告您的定制用例，我们将研究如何扩展我们的公共API。

❌ 我们的公共主题API 不包括:

  • DOM结构
  • 带有哈希后缀的CSS模块类名（通常使用[class*='myClassName']选择器进行定位）
  • React组件中不安全或禁止进行swizzle操作的部分
  • 从 @docusaurus/theme-common/internal 导入的 React 组件
  • 主题的确切视觉外观
note

当swizzling安全组件时，你可能会遇到从@docusaurus/theme-common（没有/internal子路径）导入未记录API的组件。

我们仍然维护这些API的向后兼容性（因此它们被标记为“安全”），但我们不鼓励直接使用。