跳到主要内容

发布流程

我们来讨论一下 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-pickmain 向后移植内容到 docusaurus-v2,包括向下兼容的功能以及 bug 和安全修复。 这些内容可以供那些尚未为下一版本做好准备的人使用。

信息

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

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

下一版本

下一版本(v3,在 main)是 Docusaurus 团队正在开发的版本。

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

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

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

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

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

警告

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

betarc(发布候选)阶段,我们会避免引入重大的破坏性变更。

公开 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 startdocusaurus 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"),但我们不鼓励直接使用它们。