Suggestion: Add a permanent link for the current version (docs/v9.x)

[fasttime]

What problem do you want to solve?

Currently, https://eslint.org/docs/v8.x/ links to the docs for ESLint v8, but there is no such permanent link for the docs of v9. The current link is https://eslint.org/docs/latest/, but this will change with every new major release.

In my specific case, I would like to point users to the requirements for ESLint v9, not for the latest version at the time of reading.

What do you think is the correct solution?

Add a redirect from docs/v9.x/* to docs/latest/*.

I think this is consistent with what other projects do. In the Node.js docs for example, https://nodejs.org/docs/latest-v21.x/api/ is an alias for https://nodejs.org/docs/latest/api/, and previous versions follow the same naming convention: https://nodejs.org/docs/latest-v20.x/api/ for v20, https://nodejs.org/docs/latest-v19.x/api/ for v19, etc.

Participation

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

Additional comments

No response

[nzakas]

Can you explain more about your use case? We generally don't have a version-specific link for the latest docs, so I'd like to understand more about what you're looking to do.

[fasttime]

This is inspired by self-interest, but I thought it could be useful to other projects as well to have this feature.

I maintain a tool that supports both ESLint v8 and v9. Part of the functionality of that tool depends on the version of ESLint used by the user. For example, the installation requirements will vary depending on whether they are working with v8 or v9.

To make sure that users find information that is relevant to them in the docs, I will sometimes include links to different versions of the same page in the ESLint documentation. An example:

Make sure that you are using a version of Node.js supported by your version of ESLint. See prerequisites for ESLint 8 and ESLint 9.

Currently, the links look like:

• https://eslint.org/docs/v8.x/...
• https://eslint.org/docs/latest/...

After the release of ESLint v10, the first URL will still link to the v8 docs (according to eslint/eslint#18229). The second URL will change from v9 to v10. While I expect to be around to update my project as necessary, I'd prefer to use a permanent URL when linking to a version specific page of the docs. So I would like to use https://eslint.org/docs/v9.x/... and not having to change that later.

[nzakas]

Got it, thanks for explaining. Given that, I'm 👍 to this change, but I'd like @mdjermanovic's thoughts as well before proceeding.

[mdjermanovic]

I'm fine with the idea, just not sure about the technical details, as at one point we'd like docs/v9.x/* to show docs for v9 instead of redirecting to docs/latest/* (which would then be v10+). In theory, 302 shouldn't be cached anywhere but in practice that might not be the case so we might want to do a research on that matter.

[fasttime]

I'm fine with the idea, just not sure about the technical details, as at one point we'd like docs/v9.x/* to show docs for v9 instead of redirecting to docs/latest/* (which would then be v10+). In theory, 302 shouldn't be cached anywhere but in practice that might not be the case so we might want to do a research on that matter.

So, if I understand correctly, a problem would occur when the server or a CDN decides to cache the redirect URL of a 302 response, but not the content of the redirect target (the 200 response)? In that case, after a major version bump, a user agent would be redirected to the cached location /docs/latest/* but then load fresh content from the server as if it were from /docs/v9.x/*. This is clearly something that should be avoided, especially because of search engine results. Do you have an idea what kind of research would be appropriate to determine how this situation can be prevented?

[nzakas]

I don't think we should spend too much time researching this. My understanding is that 302s are cached according to regular cache-control and expires headers. As long as we're not including those, then I think it's safe to do a redirect.

In the case where something is being cached somewhere, it probably wouldn't last for very long, and I'm willing to sacrifice the /docs/9.x URL to allow /docs/latest to work correctly.