发布流程
让我们看看 Docusaurus 如何处理**版本管理、发布和破坏性变更**。
此主题对于高度定制化的站点尤为重要，因为它们在升级时可能会遇到困难。
语义化版本控制
Docusaurus 的版本控制基于 major.minor.patch 方案，并遵循 语义化版本控制。
遵循语义化版本控制很重要，原因如下：
- 只要您只使用公共 API，它就能**保证简单的次要版本升级**
- 它遵循前端生态系统的惯例
- 新的主版本是充分记录破坏性变更的机会
- 新的主/次版本是借博客文章发布新功能的好机会
主版本
major 版本号在**每次破坏性变更**时递增。
每当发布新的主版本时，我们都会发布
- 一篇博客文章，其中包含功能亮点、主要错误修复、**破坏性变更和升级说明**。
- 一份详尽的更新日志条目
请阅读我们的公共 API 表面部分，以清楚了解我们认为什么是破坏性变更。
次要版本
minor 版本号在每次重要的向后兼容性变更时递增。
每当发布新的次要版本时，我们都会发布
- 一篇包含功能亮点和主要错误修复列表的博客文章
- 一份详尽的更新日志条目
如果您只使用我们的公共 API 表面，您应该能够立即升级！
补丁版本
patch 版本号在错误修复版本发布时递增。
每当发布新的补丁版本时，我们都会发布
- 一份详尽的更新日志条目
版本
Docusaurus 团队使用简单的开发流程，并且一次只维护一个主版本和一个 Git 分支
- **Docusaurus 3**：**稳定**版本，位于
main分支上。
新稳定版本发布后，前一个稳定版本将继续获得**3 个月**的**主要安全问题**支持。
实际上，我们会将安全修复反向移植到 docusaurus-v3 分支。否则，所有功能将冻结，非关键错误将不予修复。
建议在该时间段内升级到新的稳定版本。
公共 API 表面
Docusaurus 致力于遵循语义化版本控制。这意味着，每当 Docusaurus 公共 API 发生变更并破坏向后兼容性时，我们都会递增 major 版本号。
Docusaurus 保证公共 API 在 minor 版本之间的向后兼容性。除非您使用内部 API，否则 minor 版本升级应该很容易。
我们将概述哪些属于公共 API 表面。
核心公共 API
✅ 我们的公共 API 包括
- Docusaurus 配置
- Docusaurus 客户端 API
- Docusaurus CLI
- 预设选项
- 插件选项
- 插件生命周期 API
- 主题配置
- 核心插件路由组件属性
@docusaurus/typesTypeScript 类型- 我们仍然保留使类型更严格的自由（这可能会破坏类型检查）。
❌ 我们的公共 API **不包括**
- Docusaurus 配置
future - 所有以
experimental_或unstable_为前缀的功能 - 所有以
v<MajorVersion>_（如v6_、v7_等）为前缀的功能
对于非主题 API，任何已文档化的 API 都被视为公共 API（并将保持稳定）；任何未文档化的 API 都被视为内部 API。
API“稳定”意味着如果您在 Docusaurus 安装中递增补丁或次要版本而没有其他任何更改，运行 docusaurus start 或 docusaurus build 不应抛出错误。
主题公共 API
Docusaurus 拥有非常灵活的主题系统
- 您可以使用自定义 CSS
- 您可以swizzle任何 React 主题组件
此系统也隐式地创建了非常大的 API 表面。为了能够快速迭代并改进 Docusaurus，我们无法保证向后兼容性。
✅ 我们的公共主题 API 包括
- 主题类名
- Infima 类名和 CSS 变量
- 可以安全 swizzle 的 React 组件
- 主题用户体验
- 浏览器支持
您可能无法通过此公共 API 实现您的站点定制。
在这种情况下，请报告您的定制用例，我们将设法扩展我们的公共 API。
❌ 我们的公共主题 API **不包括**
- DOM 结构
- 带有哈希后缀的 CSS 模块类名（通常通过
[class*='myClassName']选择器定位） - 不安全或禁止 swizzle 的 React 组件
- 从
@docusaurus/theme-common/internal导入的 React 组件 - 主题的确切视觉外观
当swizzle安全组件时，您可能会遇到从 @docusaurus/theme-common 导入未文档化 API（不带 /internal 子路径）的组件。
我们仍保持这些 API 的向后兼容性（因此它们被标记为“安全”），但我们不鼓励直接使用。