发布流程
我们来讨论一下 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 包括:
- 主题类名
- 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"),但我们不鼓励直接使用它们。