Docs: provide docs for previous major versions

[That-Guy977]

Before You File a Documentation Request Please Confirm You Have Done The Following...

• I have looked for existing open or closed documentation requests that match my proposal.
• I have read the FAQ and my problem is not listed.

Suggested Changes

Provide docs for previous major versions, similar to ESLint, optionally with a banner to notify about EOL.

Affected URL(s)

https://typescript-eslint.io/rules/ and/or pages under the Docs tab.

Additional Info

ESLint Issues/PRs
eslint/eslint#18229
eslint/eslint.org#609

[kirkwaiblinger]

Drive-by: stems from discord conversation at https://discord.com/channels/1026804805894672454/1088474511759917106/1315998130990223410

[JoshuaKGoldberg]

Fun fact, we have almost this in a kind of unofficial capacity. Each PR has a Netlify preview deploy. Example: #10416 -> https://deploy-preview-10416--typescript-eslint.netlify.app

It probably wouldn't be too much work to make / augment release action(s) that, for each version:

1. Creates a branch
2. Tells Netlify to make a deployment for that branch with some OLD_VERSION env variable
3. Have the website add big "THIS IS NOT THE LATEST! GO TO THE LATEST! 🔗" notice in the presence of that variable

[bradzacher]

I'm a very strong -1 here.
I don't think we should encourage or make it easy for people to stay on old versions.
It is never more than a few hours of work to do a major upgrade and we always very purposely document the breakages and steps to work past them.

It's also rare that there's enough changes in a major that you can get 90%+++ of the way with the new docs.

We have discussed this in the past but decided against it expressly because it involves managing multiple deployments on netlify and it means that there are problems like out-of-date contributor/maintenance docs being visible/searchable, out of date sponsors, etc.

[kirkwaiblinger]

I personally find that being able to easily view older versions of rule pages (including minor versions, not just previous major) is very helpful as a user when upgrading to the latest version. If this has already been firmly decided upon previously, we don't have to rehash it, but I would be happy to make a case in favor of this if it's open for discussion.

[mwaibel-go]

I second kirkwaiblinger.

I’m currently maintaining several projects on a legacy (ts-)eslint version because I haven’t had the time to upgrade yet. I’ve just come across an instance where the autoformatter doesn’t work as intended. I would’ve appreciated the possibility to look up the appropriate rule in the docs and change the config, which would have been a simple change, rather than invest the ”few hours of work to do a major upgrade”.

[JoshuaKGoldberg]

Coming back to this: I think we should do it.

User motivation: folks keep asking for it. Even several hours of work can be too much for teams on tight deadlines.

Project motivation: we can be very very verbose in a "this is an old version! don't use it!" banner. I think this would be a great opportunity to showcase why you should really update:

• Getting the latest rule features and fixes
• Supporting new TypeScript syntax
• Continuous performance and stability improvements

Per #10483 (comment) I don't think it'll be a lot of work.