[2.0] RFC: Road to 2.0

[slorber]

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

[JoelMarcey]

cc @zpao

[HonkingGoose]

About SemVer

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.

I recommend that this project follows the Conventional Commits specification ¹. The big idea is that the PR title should always reflect the kind of change that's in the PR, for example a breaking change looks like this:

Commit message with ! to draw attention to breaking change

feat!: send an email to the customer when a product is shipped

So the "deterministic way" is for a human to figure out: "What kind of change am I making in this PR?, and then using the proper prefix like feat:, fix, chore: or whatever is appropriate".

I recommend you write down in a document what kind of changes are considered breaking, and which are considered patches/features. This way contributors can figure out themselves what kind of PR title/commit message they need to use.

Over on the Renovate bot repository we "squash merge" PRs into our main production branch, so we can always edit the commit message/PR title before the final merge, to fix any mistakes.

Optional: automating releases with semantic-release

Once you use Conventional Commits, you can then start using semantic-release to automate your release process. I don't know enough to help with setting up semantic-release. Maybe the maintainers of semantic-release are willing to help you get setup, pinging @gr2m and @travi for comments/ideas/offers to help? 😉

Automating dependency updates

I propose that issue #3552 gets added to the roadmap for the 2.0.0 release. I think you will benefit massively from using Renovate to get notified of updates, and getting automatic update PRs.

Footnotes

1. https://www.conventionalcommits.org/en/v1.0.0/ ↩

[travi]

I don't know enough to help with setting up semantic-release. Maybe the maintainers of semantic-release are willing to help you get setup, pinging @gr2m and @travi for comments/ideas/offers to help? 😉

Our getting started docs should cover most of the necessary details. If you find gaps, feel free to open a discussion under our main repository or suggest a docs improvement by opening a PR.

[slorber]

@HonkingGoose you are too fast here, we are not looking to automate any process (yet) and it's not really the point of this issue.

What we want for v2 is to be able to tell for sure if a change is a breaking change or not.

The hard part is not to add a ! to commit messages but to actually figure out a way to be sure that a ! must be added. Once we have figured this out, we'll be able to automate.

I recommend you write down in a document what kind of changes are considered breaking, and which are considered patches/features.

This is what we try to define here. To be able to tell for sure what is breaking and what is not, we have to make some code changes so that it becomes clearer.

All PRs are already squashed for a long time and commit messages are chosen carefully by core team members.

If we write this doc, it's for us, and not external contributors: because it's already hard for the core team to be sure something is to be considered as a breaking change

[HonkingGoose]

@HonkingGoose you are too fast here, we are not looking to automate any process (yet) and it's not really the point of this issue.

Oh okay, I thought it would be nice to mention semantic-release as a way to simplify the release process. 😄 🙈

I'll stop commenting on this issue now, and let you get on with things. 😉

[slorber]

Interesting read: https://tom.preston-werner.com/2022/05/23/major-version-numbers-are-not-sacred.html

Tom Preston-Werner (SemVer/GitHob creator) explains why Redwood v2.0 will be released 1 month after v1.0 (v1 was a WIP for a long time, quite similar to Docusaurus v2).

The ersioning strategy vision looks quite similar to what I'd like to set up for Docusaurus.

Being a full-stack web framework, RedwoodJS has an extensive API surface area. There is simply a lot of functionality being worked on.

We need to move quickly and iterate to stay relevant. The web framework space is a constantly moving target, and success will require rapidly improving capabilities and developer experience.

Not all changes can maintain backward compatibility without incurring unacceptable tech debt or complexity increases in the codebase. There are real development, maintenance, and velocity costs associated with supporting both the old and new ways of doing something. We need to be able to make the call to move forward with new ideas without having to incur these costs or wait many months until a marketing-approved major release can be rolled. The specific breaking change that is prompting 2.0 is this set of changes to the Baremetal deploy strategy.

We are unwilling to compromise the trust of our users by finding some excuse for shipping breaking changes in a minor release. If you know we’re serious about marking breaking changes with a major release, you can spend less time verifying that our minor releases are safe upgrades.

Some interesting things to consider:

• Do we want to bump major versions for tiny breaking changes too? IE major versions that would not contain many highlights?

• How do we make Docusaurus v1 stand out from Docusaurus v2+ ? Should we use an "epoch name" like Redwood plans to use?

[Josh-Cena]

Let's use TypeScript's versioning system😄

[Josh-Cena]

We're several minor versions past 2.0 now. Thanks everyone!