No guidance (nor build infrastructure) to note when rule options are added in specific versions of ESLint

[platinumazure]

Prelude

I'm aware that we don't specifically want to be strict about noting when rule options are added or changed in particular release versions. I am not advocating that we try to retrofit the entire site with version information. What I want to do is to make individual updates/notes possible (while providing a uniform UX).

Proposal

I would love to see some options for prefixing a paragraph/list option with a "new in version x" icon/text, in such a way that it's uniform across the site. This could simply be text conventions, or it could be something that would get replaced with an icon or otherwise styled during site generation.

The purpose of this would be to allow the team or the community to respond to user confusion when an issue comes in for an option that "does not yet exist" on the rule in the version the user is using. The team or community could add this information only in the place it was needed, without feeling obligated to try to document the ESLint version added for every rule option ever.

Progressing Further

It could be nice to have an option for developers of new features to include a "new in this version" tag/icon/text/whatever, which would transform into "new in version x" during site generation during release. This would allow contributors to note new functionality without making assumptions about what ESLint version will contain the new documentation.

Definitely out of scope for initial implementation.

[nzakas]

I think this is a problem, in general, with our documentation. We've never done a good job (or made any attempt) of nothing version differences. That was mostly because we just never sat down and figured out a scaleable way of doing this.

That said, there are a couple of approaches that could work:

1. Release a version-specific site for each version. The header should probably show the current version and then you can switch between them. We'd end up with URLs like eslint.org/v5.0.0/docs instead of just eslint.org/docs. The problem we'd have to figure out here is how to scale this, because shipping 30 different versions of the site will make cloning/updating the repo a big pain (not to mention confusing for the Algolia search).

2. We could add a placeholder like "$LATEST$" in the docs where we want the latest version to be added during deploy of the website. As we don't know what the next version will be until deployment, that would have to happen at build time. There is some hairiness around updating the docs and pushing back to the eslint repo, but should be mostly straightforward. The downside of this is that it's totally manual and we'd need to check each PR (though maybe probot could help?).

I personally think the first option is the right way to go even though it's technically more difficult.

[kaicataldo]

Not necessarily advocating for this, but I know Babel moved to Docusaurus a little while ago. Maybe @hzoo can comment on how that's been for the the Babel team.