跳至主要内容

发布流程

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

信息

对于高度定制化的站点，升级可能会遇到困难，因此本主题尤为重要。

语义化版本控制​

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

遵循语义化版本控制的原因有很多：

  • 它保证了简单的次要版本升级，只要您只使用公共 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）。

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

信息

发布新的稳定版本后，之前的稳定版本将只针对重大安全问题提供支持3 个月。否则，所有功能将被冻结，非关键性错误将不会修复。

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

下一个版本​

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

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

此版本建议早期采用者使用，他们希望尽快使用最新的 Docusaurus 功能。它也是帮助我们的一种好方法，您可以通过报告错误并提供一些反馈来帮助我们。

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

  • 使用alpha、beta或rc预发布版本
  • 使用@next npm dist 标签获取最新的预发布版本
  • 使用Canary 版本获取最新的功能
提示

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

警告

下一个版本可能会出现重大变更：详细的升级说明在变更日志和拉取请求中提供。

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

公共 API 表面​

Docusaurus 致力于遵循语义化版本控制。这意味着，每当 Docusaurus 公共 API 发生变更并破坏向后兼容性时，我们都会增加major版本号。

提示

Docusaurus 保证在minor版本之间公共 API 向后兼容。除非您使用内部 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 都被视为内部 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（没有/internal子路径）导入未记录 API 的组件。

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

编辑此页面
上次更新于 由 Sébastien Lorber 更新