跳到主要内容

发布流程

我们来讨论一下 Docusaurus 是如何处理版本、发布和破坏性变更的。

信息

这个专题对于那些比较难以升级的高度定制网站来说尤为重要。

语义化版本​

Docusaurus 版本基于 major.min.patch 模式，尊重语义版本规范。

尊重语义版本很重要，因为：

  • 可以保证小版本升级比较简单，只要你只使用公开 API
  • 符合前端生态的传统
  • 发布新的大版本时，有机会完整地记录破坏性变更
  • 发布新的大版本/小版本时，有机会通过博客介绍新功能
备注

发布 Docusaurus 2.0 花了很长很长时间。 从现在开始，Docusaurus 会更经常地发布新的大版本。 一般来说，每 2~4 个月都会发一个新的大版本。

我们不会对大版本号太有敬畏之心，但仍然会把破坏性更改放在一起，避免大版本发布太频繁。

大版本​

每次发布破坏性变更，major 版本号都会递增。

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

  • 一篇博文，包括主要功能介绍、重要 bug 修复、破坏性变更、和升级指南。
  • 完整的更新记录
提示

要清楚理解我们会将哪些作为破坏性变更，请阅读我们的公开 API 部分。

小版本​

每次发布向后兼容的重要变化时，minor 版本号都会递增。

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

  • 一篇博文，包括主要功能介绍和重要 bug 修复
  • 完整的更新记录
提示

如果你只使用我们的公开 API，那升级应该很简单！

补丁版本​

每次发布 bug 修复时，patch 版本号都会递增。

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

  • 完整的更新记录

版本​

Docusaurus 团队通常会同时开发两个大版本：

  • Docusaurus 2：稳定版本, 在 docusaurus-v2 分支
  • Docusaurus 3：预览版本，在 main 分支
备注

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

稳定版本​

我们推荐大多数 Docusaurus 用户使用稳定版本（v2，在docusaurus-v2）。

我们会定期通过 git cherry-pick 从 main 向后移植内容到 docusaurus-v2，包括向下兼容的功能以及 bug 和安全修复。 这些内容可以供那些尚未为下一版本做好准备的人使用。

信息

在新的稳定版本发布后，我们会继续为上一个稳定版本提供 3 个月 的支持，但只包括重要安全问题。 除此之外，所有功能都会被冻结，非关键的 bug 也不会被修复。

建议在这一时限内升级到新的稳定版本。

下一版本​

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

main 分支是所有 PR 的默认目标分支，包括核心团队以及外部贡献者。

我们推荐想要立即使用 Docusaurus 最新功能的早期尝试者使用这一版本。 这也是帮助我们的好方法，因为用户可以报告 bug 并提供反馈。

有三种方法来使用下一版本：

  • 使用 alpha, beta 或 rc 预发布版本
  • 通过 npm 的 @next 发布标签使用最新的预发布版本
  • 通过 canary 版本使用最新的功能
提示

下一版本通过了所有的自动化测试，Docusaurus 网站自己也在生产环境中使用此版本。 它相对来说还是很安全的。不要害怕尝试它。

警告

在下一版本开发中可能发生破坏性变更：更新日志和 PR 中有详细的升级指南。

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

公开 API​

Docusaurus 致力于尊重语义版本。 这意味着每当 Docusaurus 的公开 API 出现变化并且无法向后兼容时，我们都会增加 major 版本号。

提示

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

我们接下来会概述公开 API 包括哪些内容。

Core 的公开 API​

✅ 我们的公开 API 包括：

  • Docusaurus 配置
  • Docusaurus 客户端 API
  • Docusaurus CLI
  • 预设选项
  • 插件选项
  • 插件生命周期 API
  • 主题配置
  • 核心插件路由组件属性
  • @docusaurus/type TypeScript 类型
    • 我们仍然保留使类型更加严格（可能导致类型检查失败）的自由。

❌ 我们的公开 API 不包括：

  • Docusaurus future 配置
  • 所有以 experimental_ 或 unstable_ 为前缀的功能
  • 所有以 v<MajorVersion>_ (v6_ v7_ 等等) 为前缀的功能
提示

对于非主题 API，任何有文档的 API 都被认为是公开的（从而保证稳定性）；任何没有文档的 API 都被认为是内部的。

如果一个 API 是「稳定」的，就意味着如果你增加了 Docusaurus 的 patch 或 minor 版本号，然后不做其他任何修改，docusaurus start 或 docusaurus build 都不会抛出异常。

主题的公开 API​

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

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

这一系统也同时创造了非常庞大的 API 表面积。 为了能够快速开发，改进 Docusaurus，我们没法保证向后兼容。

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

提示

你可能无法通过这些公开 API 实现你的站点个性化。

在这种情况下，请报告你的个性化用例，这样我们可以研究如何拓展我们的公开 API。

❌ 我们的公开主题 API ** 不包括**：

  • DOM 结构
  • 带哈希后缀的 CSS 模块类名（通常在 CSS 里用 [class*='myClassName'] 选择器指向）
  • 无法安全 swizzle 或禁止 swizzle 的 React 组件
  • 从 @docusaurus/theme-common/internal 中导入内容的 React 组件
  • 主题的确切外观
备注

你可能会遇到一些能被 swizzle 的安全组件，它们从 @docusaurus/theme-common（没有 /internal 子路径）导入内容，但这些 API 没有文档。

我们仍然对这些 API 保持向后兼容性（因此把它们标记为 "safe"），但我们不鼓励直接使用它们。