发布过程
让我们看看 Docusaurus 是如何处理版本控制、发布和重大变更的。
这个主题对于可能难以升级的高度定制的站点尤其重要。
语义版本控制
Docusaurus 的版本控制基于major.minor.patch 方案，并尊重语义版本控制。
尊重语义版本控制很重要，原因有很多:
- 它保证了简单的小版本升级，只要你只使用公共 API
- 它遵循前端生态系统惯例
- 新的主版本是一个彻底记录破坏性更改的机会
- 一个新的主要/次要版本是一个通过博客文章交流新特性的机会
Releasing Docusaurus 2.0 took a very long time. From now on, Docusaurus will release new major versions more regularly. In practice, you can expect a new major version every 2–4 months.
Major version numbers are not sacred, but we still group breaking changes together and avoid releasing major versions too often.
主要版本
The major version number is incremented on every breaking change.
Whenever a new major version is released, we publish:
- a blog post with feature highlights, major bug fixes, breaking changes, and upgrade instructions.
- an exhaustive changelog entry
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.
Whenever a new minor version is released, we publish:
- a blog post with a list of feature highlights and major bug fixes
- an exhaustive changelog entry
If you only use our public API surface, you should be able to upgrade in no time!
补丁版本
The patch version number is incremented on bugfixes releases.
Whenever a new patch version is released, we publish:
- an exhaustive changelog entry
版本
Docusaurus 团队通常同时开发两个主要版本:
- Docusaurus 2: 稳定版本， 在
docusaurus-v2分支上 - Docusaurus 3: 下一个版本， 在
main分支上
稳定的版本
The stable version (v2, on docusaurus-v2) is recommended for most Docusaurus users.
We regularly backport retro-compatible features, bug and security fixes from main to docusaurus-v2 with git cherry-pick to make them available to those not ready for the next version.
After a new stable version has been released, the former stable version will continue to receive support only for major security issues for 3 months. Otherwise, all features will be frozen and non-critical bugs will not be fixed.
It is recommended to upgrade within that time frame to the new stable version.
下一个版本
The next version (v3, on main) is the version the Docusaurus team is currently working on.
The main branch is the default target branch for all pull requests, including core team and external contributions.
This version is recommended for early adopters that want to use the latest Docusaurus features as soon as possible. It is also a good way to help us by reporting bugs and giving some feedback.
There are 3 ways to use the next version:
- with an
alpha,betaorrcpre-release - with the
@nextnpm dist tag for the latest pre-release - with a canary release for the very latest features
The next version passes all our automated tests and is used by the Docusaurus site itself. It is relatively safe: don't be afraid to give it a try.
Breaking changes can happen on the next version: detailed upgrade instructions are available in the changelog and pull requests.
At the beta and rc (release candidate) phases, we avoid introducing major breaking changes.
公共 API 接口
Docusaurus commits to respecting Semantic Versioning. 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.
We will outline what accounts as the public API surface.
核心公共 API
✅ 我们的公共 API 包括:
- Docusaurus 配置
- Docusaurus 客户端 APIs
- Docusaurus CLI
- Preset 选项
- Plugin 选项
- Plugin 生命周期 APIs
- Theme 配置
- 核心插件路由组件属性
@docusaurus/typesTypeScript 类型- 我们仍然保留了使类型更严格的自由(这可能会破坏类型检查)。
对于非主题 API，任何有文档的 API 都被认为是公开的(并且将是稳定的);任何未记录的 API 都被认为是内部的。
API 是稳定的意味着如果你在没有任何其他更改的情况下增加了 Docusaurus 安装的补丁或小版本，运行Docusaurus start或Docusaurus build应该不会抛出错误。
主题化公共 API
Docusaurus 有一个非常灵活的主题系统:
- 您可以使用自定义 CSS
- 你可以swizzle任何 React 主题组件
该系统还隐式地创建了一个非常大的 API 界面。为了能够快速移动并改进 Docusaurus，我们不能保证向后兼容。
✅ 我们的公共主题 API 包括:
You may not be able to achieve your site customization through this public 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:
- The DOM structure
- 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 - The exact visual appearance of the theme
When swizzling safe components, you might encounter components that import undocumented APIs from @docusaurus/theme-common (without the /internal subpath).
We still maintain retro-compatibility on those APIs (hence they are marked as "safe"), but we don't encourage a direct usage.