8000 Docs: link to docs for previous major versions, with the appropriate caveats · Issue #10483 · typescript-eslint/typescript-eslint · GitHub
[go: up one dir, main page]
Skip to content

Docs: link to docs for previous major versions, with the appropriate caveats #10483

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
8000 2 tasks done
That-Guy977 opened this issue Dec 10, 2024 · 8 comments · Fixed by #11178
Closed
2 tasks done

Docs: link to docs for previous major versions, with the appropriate caveats #10483

That-Guy977 opened this issue Dec 10, 2024 · 8 comments · Fixed by #11178
Labels
documentation Documentation ("docs") that needs adding/updating team assigned A member of the typescript-eslint team should work on this.

Comments

@That-Guy977
Copy link

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

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
@That-Guy977 That-Guy977 added documentation Documentation ("docs") that needs adding/updating triage Waiting for team members to take a look labels Dec 10, 2024
@kirkwaiblinger
Copy link
Member

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

@JoshuaKGoldberg
Copy link
Member
JoshuaKGoldberg commented Dec 10, 2024 •
edited
Loading

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
Copy link
Member

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
Copy link
Member

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
Copy link

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
Copy link
Member
JoshuaKGoldberg commented Dec 30, 2024 •
edited
Loading

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.

@JoshuaKGoldberg
Copy link
Member

Chatted internally: nobody internally wants to block this, and I'm excited enough about it to want to push it forward. Assigning to the team. 🚀

@JoshuaKGoldberg JoshuaKGoldberg added team assigned A member of the typescript-eslint team should work on this. and removed triage Waiting for team members to take a look labels Feb 24, 2025
@JoshuaKGoldberg
Copy link
Member

Chatted internally: nobody internally wants to block this, and I'm excited enough about it to want to push it forward. Assigning to the team. 🚀

Note that we're going to make the old version docs very verbosely yell at the users to switch to new versions.

"You're looking at docs for old versions. Don't use old versions. They are slower, more buggy, and don't support new TS syntax. Rule failures do not block upgrading, see (blog post). We do not support old versions. Go upgrade now!"_

@JoshuaKGoldberg JoshuaKGoldberg mentioned this issue May 6, 2025
Merged
3 tasks
@JoshuaKGoldberg JoshuaKGoldberg changed the title Docs: provide docs for previous major versions Docs: link to docs for previous major versions May 6, 2025
@JoshuaKGoldberg JoshuaKGoldberg changed the title Docs: link to docs for previous major versions Docs: link to docs for previous major versions, with the appropriate caveats May 6, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
documentation Documentation ("docs") that needs adding/updating team assigned A member of the typescript-eslint team should work on this.
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

docs: add big announcement notice for old major versions JoshuaKGoldberg/typescript-eslint
5 participants
@JoshuaKGoldberg @bradzacher @kirkwaiblinger @That-Guy977 @mwaibel-go
0