Suggestion: Add a permanent link for the current version (`docs/v9.x`) about eslint.org HOT 11 CLOSED

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.

from eslint.org.

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.

from eslint.org.

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

from eslint.org.

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.

from eslint.org.

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?

from eslint.org.

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.

from eslint.org.

@mdjermanovic what do you think of my previous comment?

from eslint.org.

Sounds good to me 👍

Marked as accepted.

from eslint.org.

We don't keep documentation for the minor version at this time; x for v9.x doesn't exist. And we hardly ever see this form in the documentation of other packages, usually just v9. Maybe consider removing the x?

I know the node documentation uses this form, but I don't think it should be the majority.

from eslint.org.

We don't keep documentation for the minor version at this time; x for v9.x doesn't exist. And we hardly ever see this form in the documentation of other packages, usually just v9. Maybe consider removing the x?

I know the node documentation uses this form, but I don't think it should be the majority.

@kecrily Thanks for the feedback. Can you explain what you suggest to do with existing docs/v8.x/* links?

from eslint.org.

We use ".x" to indicate that it represents the entire line, such as v8.x or v9.x, not just one particular version. This is a common way to indicate this, so I think it's useful to keep it.

from eslint.org.