Change Request: Permanent solution for multiple docs sites

[mdjermanovic]

ESLint version

v9.0.0-rc.0

What problem do you want to solve?

Currently, our docs site implementation supports publishing three versions: head (development), next (prerelease), and latest.

When we release v9 final, we'd like the docs for v8.x (v8.57.0) to be available too. Publishing docs for previous versions is currently not supported.

Also, whenever we release a new version, the version selectors on all docs sites should ideally be updated automatically.

Here's an overview of docs sites we'll have in the future.

List Item = entry in version selectors.

Currently, we have:

List Item	Branch	URL Path
HEAD	main	/docs/head/
v9.0.0-rc.0	next	/docs/next/
v8.57.0	latest	/docs/latest/

When we release v9 final, we'll have:

List Item	Branch	URL Path
HEAD	main	/docs/head/
v9.0.0	latest	/docs/latest/
v8.57.0	v8.x	/docs/v8.x/

When we release first v10 prerelease (e.g., after v9.26.0), we'll have:

List Item	Branch	URL Path
HEAD	main	/docs/head/
v10.0.0-alpha.0	next	/docs/next/
v9.26.0	latest	/docs/latest/
v8.57.0	v8.x	/docs/v8.x/

When we release v10 final, we'll have:

List Item	Branch	URL Path
HEAD	main	/docs/head/
v10.0.0	latest	/docs/latest/
v9.26.0	v9.x	/docs/v9.x/
v8.57.0	v8.x	/docs/v8.x/

What do you think is the correct solution?

As for the v8.x docs:

1. We should update this code to handle vNN.x branches.
2. We should update eslint.org redirects to enable docs/v8.x, similar to eslint/eslint.org@f10378f. Netlify is already set up to deploy from the v8.x branch.

As for the version selectors, that's more complicated. The idea is to:

1. Make a json file with data for all versions that should be currently displayed in version selectors: an array of { version, branch, pathPrefix }.
2. Update the release process to update this file according to what version has just been released.
3. Update docs site code to fetch this file from the main branch during builds (similar to 19370e5) and use that data in version selectors.
4. Add a workflow that runs after each release and triggers rebuilds of all docs sites on Netlify (similar to 473411e).

Does this make sense?

Participation

• I am willing to submit a pull request for this change.

Additional comments

Notes:

1. Changes in the docs site code should be ported to all relevant branches (e.g., to v8.x).

Questions:

1. What do we plan to do with https://eslint.org/docs/next/ when we release v9 final - shall we keep this docs site or shall we drop it until v10 prereleases?

[nzakas]

This sounds like a proposal just to update how we fill in the dropdown vs. more wholesale changes?

And just a reminder, when you move an issue into "Feedback Needed", please ping @eslint/eslint-team

[mdjermanovic]

Yes, perhaps the wording "permanent" wasn't appropriate. I only intended to address synchronization of version dropdowns on docs sites, which is a problem we'll have when we release the v9 final. The solution would also account for future prereleases and future major releases (v10, v11...) so that we don't have the same problem every year, thus "permanent". The sites would keep building from respective branches, only the version list would be fetched from another place (e.g., from the main branch). Did you have something else in mind for a long-term solution?

[nzakas]

That all sounds good to me. It's just the title sounded almost like "let's rethink how we're doing multiple docs sites in general", which I do think is a conversation we need to have...but for now, happy to get the dropdown synchronization correct. 😄

[mdjermanovic]

Working on this.