This is a living draft: we will keep it up-to-date.

It's possible that what you read now changes significantly over time.

The road to 2.0

A meta-issue to prepare ourselves for the official 2.0 release.

GitHub milestone including related issues to track: https://github.com/facebook/docusaurus/milestone/15

Current state of 2.0.beta

• We have been in alpha/beta for a very long time
• Not releasing 2.0 is confusing for the community, bad for marketing, and we shouldn't delay it much more
• For most users, Docusaurus is stable and upgrading is easy
• For power users, some customizations remain fragile and might break when upgrading

Remaining problems:

• some quite common site customizations remain too complex/fragile to achieve
• the theming API surface is too implicit, it's hard to understand what is public/private API surface
• docusaurus swizzle is confusing, does not offer the best DX, and does not nudge users to adopt site customization best practices

Respecting SemVer

Once 2.0 is released, we really want to respect Semantic Versioning.

A breaking change should lead us to increase the major version number.

This also means that we shouldn't be afraid to release new major versions of Docusaurus quite soon.

For example, we could end up releasing Docusaurus 5 in 2022, this is what many other frameworks do (Next.js 12, Electron 16, Expo 44...).

A major version should not be synonymous with a total rewrite of Docusaurus like it was the case for v1 -> v2.

Respecting SemVer is important for multiple reasons:

• It is a reasonable expectation from our user base
• It is a marketing opportunity: each major version could have a dedicated blog post with an overview of new features highlight and breaking changes
• Users that only use the public API surface can safely upgrade to a new minor version: they shouldn't need to read changelogs nor test their site in depth.

Adopting SemVer now is complicated:

• Adopting SemVer is only possible if we have a deterministic way to qualify a PR as a breaking change
• Our theming public API is too unclear for, and we don't have strict rules to tell if a PR is for sure a breaking change.

Goal for 2.0

• Make the public theming API surface more explicit
• Communicate better what is safe/unsafe to swizzle
• Rework the "swizzle DX"
• Encourage users to adopt best practices that make customizations less fragile
• Do some final cleanup: it's a good time to remove/refactor some old/deprecated/confusing APIs

The goal is not to make all possible customizations use-cases possible through a public API, but only to make it clear what the public API is. We will try to allow the most common customizations to be made through a public API, but not in an exhaustive way, and swizzling unsafe private APIs will remain possible for non-covered use-cases.

Tasks for 2.0

Tasks will be added the 2.0 milestone: https://github.com/facebook/docusaurus/milestone/15

We will inspect our site showcase sites to analyze the most common customization patterns and see how to make them more straightforward.

If your site is not in the Docusaurus showcase, please submit it 🙏

Or at least report your customization use-cases in the dedicated issue: #5468

After 2.0 release

At this point:

• we should have a clear public API surface
• we should be able to respect SemVer

There are a lot of important issues and features that we plan to address, that will come after 2.0, in upcoming major versions.

See for example the 3.0 milestone (draft): https://github.com/facebook/docusaurus/milestone/16

Note: this does not mean that these important features are delayed, it is just that we want 2.0 to land asap.

I believe releasing a new major version per trimester is a good release cadence, but we'll figure this out.

Git organization

We'll start working on a 3.0 branch, but keep fixing bugs and implement small improvements in 2.0.

We will have 2 live git branches:

• main for 2.x (mostly bugfixes)
• next for 3.0 (work-in-progress)

Both branches will publish canary releases to make it easy to test newly merged features and provide feedback from early adopters.

We'll regularly merge 2.0 in 3.0.

Occasionally, we may backport important fixes/features from 3.0 to 2.0

Once 3.0 is released (or at least when it's ready and in RC phase), we'll merge next in main

To avoid bumping the major version too regularly, we'll throttle/batch the planned breaking changes for the next major release

That's all, feel free to provide any feedback here or in any of the milestone issues: https://github.com/facebook/docusaurus/milestone/15