发布流程
我们来讨论一下 Docusaurus 是如何处理版本、发布和破坏性变更的。
这个专题对于那些比较难以升级的高度定制网站来说尤为重要。
语义化版本
Docusaurus 版本基于 major.min.patch 模式，尊重语义版本规范。
尊重语义版本很重要，因为：
- 可以保证小版本升级比较简单，只要你只使用公开 API
- 符合前端生态的传统
- 发布新的大版本时，有机会完整地记录破坏性变更
- 发布新的大版本/小版本时，有机会通过博客介绍新功能
大版本
主版本号会在每个大版本更新时变更。
当新的主版本发布后，我们会同时发布：
- 一篇博文，包括主要功能介绍、重要 bug 修复、破坏性变更、和升级指南。
- 完整的更新记录
要清楚理解我们会将哪些作为重大变更，请阅读我们的公开 API 部分。
小版本
每次发布向后兼容的重要变化时，minor 版本号都会递增。
每次发布新的小版本时，我们会同时发布：
- 一篇博文，包括主要功能介绍和重要 bug 修复
- 完整的更新记录
如果你只使用我们的公开 API，升级应该非常简单！
补丁版本
每次发布 bug 修复时，patch 版本号都会递增。
每次发布新的补丁版本时，我们会发布：
- 完整的更新记录
版本
Docusaurus团队用一个简单的开发过程，并且仅在一个主要版本和一个Git分支同时运行：
- Docusaurus 3： 稳定 的版本，位于
main分支。
在新的稳定版本发布后，我们会继续为上一个稳定版本提供 3 个月 的支持，但只包括重要安全问题。
实际上，我们将把安全修复支持到 docusaurus-v3 分支。 除此之外，所有新功能都不会应用于旧版本，非关键的 bug 也不会被修复。
建议在这一时限内升级到新的稳定版本。
公开 API
Docusaurus 致力于尊重语义版本。 这意味着每当 Docusaurus 的公共 API 出现变化并且无法向后兼容时，我们都会增加 主 版本号。
Docusaurus 保证在 小 版本间公开 API 的向后兼容性。 除非你使用内部 API，否则 小 版本升级应该是很容易的。
我们接下来会概述公共 API 包括哪些内容。
核心公共 API
✅ 我们的公共 API 包括：
- Docusaurus 配置
- Docusaurus 客户端 API
- Docusaurus CLI
- 预设选项
- 插件选项
- 插件生命周期 API
- 主题配置
- 核心插件路由组件属性
@docusaurus/typeTypeScript 类型- 我们仍然保留使类型更加严格（可能导致类型检查失败）的自由。
❌ 我们的公共 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 包括：
- 主题类名
- Infima 类名和 CSS 变量
- 可以安全 swizzle 的 React 组件
- 主题的用户体验
- 浏览器支持
你可能无法通过这些公开 API 实现你的站点个性化。
在这种情况下，请报告你的个性化用例，这样我们可以研究如何拓展我们的公开 API。
❌ 我们的公共主题 API 不包括：
- DOM 结构
- 带哈希后缀的 CSS 模块类名（通常在 CSS 里用
[class*='myClassName']选择器指向） - 无法安全 swizzle 或禁止 swizzle 的 React 组件
- 从
@docusaurus/theme-common/internal中导入内容的 React 组件 - 主题的确切外观
你可能会遇到一些能被 swizzle 的安全组件，它们从 @docusaurus/theme-common（没有 /internal 子路径）导入内容，但这些 API 没有文档。
我们仍然对这些 API 保持向后兼容性（因此把它们标记为 "safe"），但我们不建议直接使用它们。