Upgrade Docusaurus from ^2.4.3 to ^3.0.0

[tukib]

Upgrade Proposal

Docusaurus v3 now has a stable release. The version we use, Docusaurus v2, has entered maintenance mode for major security issues, and will be deprecated after 31 January 2024¹.

This upgrade is:

• required for security.
• advantageous for new features & improvements.

Tasks

• Dependency Upgrade Policy #35
• Upgrade proposal assessed and in line with policy.
• Upgrade to Docusaurus v3 #37

Future Work?

• Use typescript files for configs

Footnotes

1. Docusaurus v3 Announcement Announcing Docusaurus 3.0 - ↩

[tukib]

While reading the announcement to define the problem, I noted down the features and breaking changes that I thought were relevant, and would make a good base for discussion and evaluating the decision to upgrade.

New Features

In addition to the bug fixes and performance improvements that Docusaurus v3 implements, the new release enables several new features¹². Some of note are:

• Defining custom directives such as :textDirective, ::leafDirective, and :::containerDirective.

• Docusaurus configuration with ESM or TypeScript for better DX (site config, docs sidebar, plugins and presets).

• Unlisted page option, making them uncrawlable. This supplements the existing draft page option which excludes pages from production builds.

• Building the site in dev mode, making debugging easier without relying on the live development script.

• Additional linting rules such as catching usage of <a> instead of Docusaurus <Link>.

• Benefits that come with React v18 such as new/upcoming features and performance improvements. For example, React Server Components will bring a substantial improvement to bundle size and page load times, which the Docusaurus team can implement on their side³.

• Support for additional Mermaid diagram types and async rendering.

Breaking Changes

Docusaurus handles most breaking changes internally¹, for our usage of it we only need to consider:

• #9189: new default blog RSS feed limit of 20 entries
• #9308: fix and re-introduce the :::warning admonition, deprecate :::caution
• #9310: remove the legacy versioned sidebar id prefix, used for sites versioned before v2.0.0-beta.10 (December 2021)
• #7966: refactor docs theme components, eventually requiring to you re-swizzle them

I do not believe any of those four items applies to us?

Regarding the remaining breaking changes of our direct dependencies:

• Node.js v16 -> v18 (ours: v20 ✅)
• React v17 -> v18 (ours: v17 ❌)
  • We have very few (if any) custom react components to consider, so this is unlikely to be an issue.
  • Migration Guide: React 18 Upgrade Guide
• MDX v1 -> v3 (ours: v1 ❌)
  • We have not populated this wiki with many pages yet, making now the best time to migrate if we choose to upgrade.
  • The overall format for documents is unchanged.
  • Migration Guides:
    • Migrating from v1 to v2
    • Migrating from v2 to v3
• TypeScript v4 -> v5 (ours: v5 ✅)

There were several other changes we do not explicitly depend on:

• prism-react-renderer v1 -> v2
• react-live v2 -> v4
• Mermaid v9 -> v10
• import-fresh v3 -> jiti v1
• remark-emoji v2 -> v4

Footnotes

1. Docusaurus v3 Announcement Announcing Docusaurus 3.0 - ↩ ↩²

2. Docusaurus v3 release notes: 3.0.0 (2023-10-31) - ↩

3. Support React Server Components: docusaurus #9089 - ↩

[seanmakesgames]

This issue write up is great. Most, if not all of the information to make the decision is in the issue.

Some opportunities for improvement:

1. upgrading dependencies is a well understood and documented problem. Use a reference to a good write up (or any write-up) instead of re-explaining the general problem in your problem statement. Save that space for the specific details of the problem related to our needs. (like what specific problems that we have that upgrading will address) here's the first result of my search
2. In the goal section, you have conditionals which is a smell (process smell) for me that we haven't broken the issue down enough. In this case however, upgrading dependencies is a (/should be) a well understood process with conditionals in it.
3. The scope of an 'issue' should be very tight, so the 'non-goals' section should not be relevant / important and I think we can generally leave it out of our issues
4. generally, we should not be listing out deliverables inside of issues, but we are still figuring the right balance of this out. I've done a line-for-line breakdown on whether they should be in there and why.

Evaluate the issue description.

this is part of issue review standards and should not be written out

Document specific features/improvements an upgrade would bring.

this is part of dependency upgrade review and should be documented elsewhere

Document general breaking changes and link migration guides.

this is part of dependency upgrade review and should be documented elsewhere

🔍 Evaluate the benefits and drawbacks of upgrading to Docusaurus v3.

This is the same as 'determine if we upgrade' and should be part of dep upgrade process (documented elsewhere)

Determine whether an updated build works as-is, or needs migration.

This does not apply to our current situation (having not released yet). This is also part of the general PR acceptance process. and should be documented elsewhere

❓ Determine if we upgrade to Docusaurs v3 now.
🔧 Create a branch and draft PR, and begin the upgrade process.
Migrate/fix any broken parts due to the upgrade.
Produce a brief test plan for any existing wiki content.

this is part of dependency upgrade review and should be documented elsewhere

🌱 Open PR for review, using our test plan for evaluation.
Address any issues or comments.
✅ Merge the PR.
this is standard PR / issue workflow and should not be listed

opinions:

1. I'm with @danswann, this upgrade should be a safe one to do and has a great deal of benefits.
2. At first I was on the fence on whether it was the right time to be writing up the dependency upgrade policy / process, but now I actually think having something very basic in place is a prerequisite to this item. -- where the in-scope deliverable is to update the process with our learnings & details.
3. Please create an issue (something like): "Decide Dependency Upgrade Policy / Process", then update your issue description using the feedback above.

[seanmakesgames]

The entire issue is completed once the upgrade PR is merged, or a defer/no decision is addressed with an appropriate outcome. I.e. our goals are met.

part of the general issue/PR workflow. don't include

For each task we require involvement from at least three contributors, and have every comment addressed before marking it as complete.

should be covered in some way in the dependency upgrade policy / process and not here.

[tukib]

Thanks for the feedback @seanmakesgames, I've now updated the issue description, and opened an issue for a dependency upgrade policy.

I've changed the tasks to reflect that we will be revisiting this issue as we develop the upgrade policy.