Website: should we keep docs of old versions available?

[JoshuaKGoldberg]

Following up on:

• Rule docs on website should show the latest version, not what's in the main branch #5939
• docs(website): add version to header, and documented branch flow #6055

Right now we only include docs for the latest version of @typescript-eslint/ packages on the website. That's good enough for most users.

But! It might be nice if we could also include docs for older versions. Sometimes folks are stuck on old versions, or just curious. Docusaurus has a feature for this: https://docusaurus.io/docs/versioning. The feature comes at a cost:

⚠️ Caution
Think about it before starting to version your documentation - it can become difficult for contributors to help improve it!

Most of the time, you don't need versioning as it will just increase your build time, and introduce complexity to your codebase. Versioning is best suited for websites with high-traffic and rapid changes to documentation between versions. If your documentation rarely changes, don't add versioning to your documentation.

I do worry about the potential added development cost of onboarding to Docusaurus versioning. Developers being able to contribute to the docs is very important to us. Getting in the way of that is a Bad.

Is there anybody out there who would really want old docs available?

[bradzacher]

I personally don't think it's worth-while.
If someone wants old versions then we have GH tags to help them go back in time to specific versions.

[santiagofn]

Hi!

In corporate environments it's not unusual to keep major versions unchanged for a long time. That's the case of the project I'm working on nowadays: current typescript-eslint version is 6.5.0, and this project's version is 5.6.0. I needed to find info about version 5.6.0 and failed.

If you ask me, having previous releases documentation available is a must for so widely-used packages (unless you think everyone is using the last version, which is not happening in the corporate world). Using GH tags is not a viable solution for user wanting to read docs, not .md files using GH navigator. I've read https://docusaurus.io/docs/versioning and the only folder developers should modify if versioning is enabled would be docs (assuming they contribute to the new version). But an extra burden will be added to each release (a new version... folder should be created, etc.).

[santiagofn]

Sorry, I confused the version. It's in fact 5.62.0.

As Brad said, when dealing with multiple projects and requests it's not always easy to prioritize bumping versions to a new major.

Thanks for the pkg docs hint. But as I mentioned, it means navigating through .md files. It'd be great to be able to use a webpage.

[bradzacher]

The vast majority of docs should be compatible with v5 - rules are pretty static version-to-version and even across the major we don't tend to change much aside from removing things.

[santiagofn]

Configurations seem to have changed. I found that v5 config recommended-requiring-type-checking has been replaced by recommended-type-checked in v6 and that stylistic... configs don't exist in v5.

[cdavie-artium]

I'm also in a corporate environment, using v5, looking for configuration docs that are different between v5 and v6. I don't necessarily get to choose when we prioritize upgrading old packages vs other work on our plate, so while it's true that we could upgrade, realistically I have no idea when we actually will. So I wish it were easier to find the old docs.

[bradzacher]

@cdavie-artium you can use the tag switcher on the github UI to select the relevant version tag. You won't get the fully rendered docs in a website - but you'll be able to browse the markdown files which aren't too different.

[JoshuaKGoldberg]

Here's how you can spin up a local dev server for any arbitrary tag:

git clone https://github.com/typescript-eslint/typescript-eslint
cd typescript-eslint
git checkout v5.62.0
yarn
yarn nx run website-eslint:build
yarn start

Note that if yarn start fails with a message about export = config, add this before yarn start:

sed -i '' '/swc: true/d' packages/website/docusaurus.config.js

See #7165.

[santiagofn]

Thanks, Joshua. I'll look into this.

[JoshuaKGoldberg]

Closing this out as it doesn't seem actionable for us. We definitely don't have the time to maintain a deployment with historical versions - even if we use the latest and greatest built-in Docusaurus support. Given that there are several ways to view docs mentioned in this discussion, we don't feel a strong need to take any action. Thanks y'all!