Skip to content

docs: update to docusaurus 3.10#19522

Open
317brian wants to merge 4 commits into
apache:masterfrom
317brian:310-upgrade-docusaurus
Open

docs: update to docusaurus 3.10#19522
317brian wants to merge 4 commits into
apache:masterfrom
317brian:310-upgrade-docusaurus

Conversation

@317brian

@317brian 317brian commented May 26, 2026

Copy link
Copy Markdown
Contributor

druid repo equivalent of apache/druid-website-src#576. This PR does the minimum for an upgrade to 3.10 to minimize disruption.

A followup PR will do:

  • MDX conversion as described in the upgrade email to the dev list
  • Turning off backwards compatibility features to prepare for the 4.0 upgrade

Description

Fixed the bug ...

Renamed the class ...

Added a forbidden-apis entry ...

Release note


Key changed/added classes in this PR
  • MyFoo
  • OurBar
  • TheirBaz

This PR has:

  • been self-reviewed.
  • added documentation for new or modified features or behaviors.
  • a release note entry in the PR description.
  • added Javadocs for most classes and all non-trivial methods. Linked related entities via Javadoc links.
  • added or updated version, license, or notice information in licenses.yaml
  • added comments explaining the "why" and the intent of the code wherever would not be obvious for an unfamiliar reader.
  • added unit tests or modified existing tests to cover new code paths, ensuring the threshold for code coverage is met.
  • added integration tests.
  • been tested in a test Druid cluster.

@317brian 317brian marked this pull request as ready for review June 1, 2026 21:07
@317brian 317brian force-pushed the 310-upgrade-docusaurus branch from 56986fb to 035b70a Compare June 1, 2026 21:07

@FrankChen021 FrankChen021 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Severity Findings
P0 0
P1 0
P2 2
P3 0
Total 2
Severity Findings
P0 0
P1 0
P2 2
P3 0
Total 2

Reviewed 2 of 2 changed files.


This is an automated review by Codex GPT-5.5

Comment thread website/package.json
"@docusaurus/plugin-client-redirects": "^3.10.1",
"@docusaurus/preset-classic": "^3.10.1",
"@docusaurus/theme-mermaid": "^3.10.1",
"@docusaurus/faster": "^3.10.1",

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Regenerate the tracked website lockfile

The PR updates Docusaurus to 3.10.1 and adds @docusaurus/faster plus @mermaid-js/layout-elk, but website/package-lock.json is still tracked with the old 3.7.0 graph and docusaurus@1.14.7. A clean npm ci will reject the out-of-sync manifest/lockfile, and lockfile-based installs will not get the intended dependency graph. Regenerate and commit website/package-lock.json with the repo's npm version.

Comment thread website/package.json
"@docusaurus/faster": "^3.10.1",
"clsx": "^1.1.1",
"docusaurus": "^1.14.7",
"docusaurus-lunr-search": "^3.6.0",

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Rewrite legacy Docusaurus scripts after removing v1

The removed docusaurus@1.14.7 package is the provider for legacy binaries like docusaurus-examples, docusaurus-publish, docusaurus-version, docusaurus-rename-version, and docusaurus-write-translations, while the remaining Docusaurus package exposes the docusaurus CLI. After a clean install with the regenerated lockfile, the existing scripts at the top of package.json will fail with command-not-found unless they are converted to Docusaurus 3 CLI forms or removed.

@FrankChen021 FrankChen021 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Severity Findings
P0 0
P1 0
P2 2
P3 0
Total 2

Reviewed 3 of 3 changed files.


This is an automated review by Codex GPT-5.5

Comment thread website/package.json
"@docusaurus/plugin-client-redirects": "^3.7.0",
"@docusaurus/preset-classic": "^3.7.0",
"@docusaurus/theme-mermaid": "^3.7.0",
"@docusaurus/core": "^3.10.1",

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Regenerate the website lockfile with the Docusaurus upgrade

This PR updates the website dependencies to Docusaurus 3.10.1 and adds new packages, but website/package-lock.json is unchanged: its root entry still declares the old ^3.7.0 Docusaurus ranges and the resolved graph still pins 3.7.0 while missing the new direct dependency entries. A clean reproducible install such as npm ci will reject the mismatch, and lockfile-based consumers will not be testing the dependency graph this PR intends to ship. Please regenerate and commit website/package-lock.json with the same package manager used for the website.

Comment thread README.md
Make documentation and tutorials updates in [`/docs`](https://github.com/apache/druid/tree/master/docs) using [Markdown](https://www.markdownguide.org/) or extended Markdown [(MDX)](https://mdxjs.com/). Then, open a pull request.

To build the site locally, you need Node 18 or higher and to install Docusaurus 3 with `npm|yarn install` in the `website` directory. Then you can run `npm|yarn start` to launch a local build of the docs.
To build the site locally, you need Node 22 or higher and to install Docusaurus 3 with `npm|yarn install` in the `website` directory. Then you can run `npm|yarn start` to launch a local dev preview of the docs.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Keep the documented Node requirement in sync with build tooling

The README now says the docs require Node 22 or higher, but the actual website metadata and automation still point at older runtimes: website/package.json allows >=18.0 and Volta pins 18.20.7, while .github/scripts/web-checks.sh installs the web-console Maven-configured Node 20.9.0 before running the docs build. If Docusaurus 3.10 now requires Node 22 for this site, contributors using Volta and the existing web checks will still run unsupported Node versions; otherwise the new README requirement is misleading. Please update the package metadata and CI/tooling Node version, or keep the README aligned with the supported runtime.

@FrankChen021 FrankChen021 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have reviewed the code for correctness, edge cases, concurrency, and integration risks; no issues found.

Reviewed 4 of 4 changed files.


This is an automated review by Codex GPT-5.5

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants