发布流程

Let's see how Docusaurus handles versioning, releases and breaking changes.

信息

这个专题对于那些比较难以升级的高度定制网站来说尤为重要。

语义化版本

Docusaurus versioning is based on the major.minor.patch scheme and respects Semantic Versioning.

尊重语义版本很重要，因为：

• It guarantees simple minor version upgrades, as long as you only use the public API
• 符合前端生态的传统
• 发布新的大版本时，有机会完整地记录破坏性变更
• 发布新的大版本/小版本时，有机会通过博客介绍新功能

大版本

The major version number is incremented on every breaking change.

当新的主版本发布后，我们会同时发布：

• a blog post with feature highlights, major bug fixes, breaking changes, and upgrade instructions.
• 完整的更新记录

提示

Read our public API surface section to clearly understand what we consider as a breaking change.

小版本

The minor version number is incremented on every significant retro-compatible change.

每次发布新的小版本时，我们会同时发布：

• 一篇博文，包括主要功能介绍和重要 bug 修复
• 完整的更新记录

提示

If you only use our public API surface, you should be able to upgrade in no time!

About End-of-Life Node.js versions

我们可能会在 Docusaurus 的次要版本中放弃对已终止生命周期的 Node.js 版本的支持。 Check the Node.js support policy section for more details.

补丁版本

The patch version number is incremented on bugfixes releases.

每次发布新的补丁版本时，我们会发布：

• 完整的更新记录

Node.js 支持政策

Docusaurus 的每个主要版本都支持一个最小的 Node.js 版本。 这种追溯兼容性将一直保留到该版本的发布。 这种运行时向后兼容性将保存在所有次要版本的发行线，但生命周期已终止的版本除外。

Support for End-of-Life versions

On minor releases, we reserve the right to drop support for Node.js versions that reached End-of-Life (Node.js release process and schedule. We do not consider it a Docusaurus breaking change. 我们强烈建议使用有维护的 Node.js 版本。 Beware that End-of-Life Node.js versions do not receive security updates anymore.

版本

Docusaurus团队用一个简单的开发过程，并且仅在一个主要版本和一个Git分支同时运行：

• Docusaurus 3: the stable version, on the main branch.

How we will ship the next version

Once we are ready ship Docusaurus 4, we will:

• 创建一个 docusaurus-v3分支
• 合并重大更新到main当前分支
• 直接从 main 分支发布新版本

Security fixes policy

After a new stable version has been released, the former stable version will continue to receive support for major security issues for 3 months.

实际上，我们将把安全修复支持到 docusaurus-v3 分支。 除此之外，所有新功能都不会应用于旧版本，非关键的 bug 也不会被修复。

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

公开 API

Docusaurus 致力于尊重语义版本。 This means that whenever changes occur in Docusaurus public APIs and break backward compatibility, we will increment the major version number.

提示

Docusaurus guarantees public API retro-compatibility across minor versions. Unless you use internal APIs, minor version upgrades should be easy.

我们接下来会概述公共 API 包括哪些内容。

核心公共 API

✅ 我们的公共 API 包括：

• Docusaurus 配置
• Docusaurus 客户端 API
• Docusaurus CLI
• 预设选项
• 插件选项
• 插件生命周期 API
• 主题配置
• 核心插件路由组件属性
• @docusaurus/types TypeScript types
  • 我们仍然保留使类型更加严格（可能导致类型检查失败）的自由。

❌ Our public API excludes:

• Docusaurus config future
• All features prefixed by experimental_ or unstable_
• All features prefixed by v<MajorVersion>_ (v6_ v7_, etc.)

提示

对于非主题 API，任何有文档的 API 都被认为是公开的（从而保证稳定性）；任何没有文档的 API 都被认为是内部的。

An API being "stable" means if you increment the patch or minor version of your Docusaurus installation without any other change, running docusaurus start or docusaurus build should not throw an error.

主题公共 API

Docusaurus 拥有一个非常灵活的主题系统：

• 你可以用自定义 CSS
• You can swizzle any React theme component

这个系统同时也创造了非常庞大的 API 应用层。 为了快速迁移并改进 Docusaurus，我们没法保证向后兼容。

✅ 我们的公共主题 API 包括：

• Theme class names
• Infima class names and CSS variables
• React components that are safe to swizzle
• 主题的用户体验
• 浏览器支持

提示

你可能无法通过这些公开 API 实现你的站点个性化。

In this case, please report your customization use case and we will figure out how to expand our public API.

❌ Our public theming API excludes:

• DOM 结构
• CSS module class names with a hash suffix (usually targeted with [class*='myClassName'] selectors)
• React components that are unsafe or forbidden to swizzle
• React components that import from @docusaurus/theme-common/internal
• 主题的确切外观

备注

When swizzling safe components, you might encounter components that import undocumented APIs from @docusaurus/theme-common (without the /internal subpath).

我们仍然对这些 API 保持向后兼容性（因此把它们标记为 "safe"），但我们不建议直接使用它们。