Update compatibility docs

[fatso83]

Purpose (TL;DR) - mandatory

Close #2359 by updating the docs to reflect our current stance.

Background (Problem in detail) - optional

Our docs state that we support Safari 9 and IE 11 - which we do not. This creates bugs such as #2358.

Solution

Point to the up-to-date reference and talk in general terms about our strategy.

How to verify - mandatory

1. Check out this branch
2. Follow steps in our docs repo to see local version.

[mroderick]

Very nice 👍

[mroderick]

You might also want to update README.md

[fatso83]

@mroderick I got some new questions after inspecting the README and the linked COMPATIBILITY.md file.

The compat file touts itself as being the canonical reference. This prompts some questions.

1. Maybe it is wrong to point to the eslint-config and I should just point this compat file instead?
2. How can we keep the docs site, the the compatibility file and the plugin in sync? Copy-on-install?
3. I see the compat document state that we use eslint-plugin-compat, but I do not see it as a direct dependency, although it is in the lock file. It is also not mentioned in our config, nor the shared config. How is this being enforced?

[mroderick]

1. Maybe it is wrong to point to the eslint-config and I should just point this compat file instead?

I agree, that's a better approach.

2. How can we keep the docs site, the the compatibility file and the plugin in sync? Copy-on-install?

I have not figured that out yet.

What do you mean by copy-on-install? Maybe that's the solution?

3. I see the compat document state that we use eslint-plugin-compat, but I do not see it as a direct dependency, although it is in the lock file. It is also not mentioned in our config, nor the shared config. How is this being enforced?

It is installed in consuming projects as a dependency of @sinonjs/eslint-config

[fatso83]

Mange tak, Morgan!

What do you mean by copy-on-install? Maybe that's the solution?

Since the browserlist file is text and in our code base, and our docs are also in the same code base, then we could use that file to update other documents by running some post-build script when doing npm run build or something. Just loose thoughts. Something like

<!-- browserlist start -->
blabla, contents of .browserlist from eslint-config
<-- browserlist end-->

and replace the bits between the magic start and end comments each time.

For now, I guess it's much easier to talk in general terms and point to some code for the most specific up-to-date details.

[mroderick]

Since the browserlist file is text and in our code base, and our docs are also in the same code base, then we could use that file to update other documents by running some post-build script when doing npm run build or something. Just loose thoughts. Something like

<!-- browserlist start -->
blabla, contents of .browserlist from eslint-config
<-- browserlist end-->

and replace the bits between the magic start and end comments each time.

For the markdown documents, I think that's a great idea.
For the .browserslistrc file, we can replace it outright.

For now, I guess it's much easier to talk in general terms and point to some code for the most specific up-to-date details.

I agree, that's a good approach 👍

[fatso83]

sinonjs/eslint-config#8

[fatso83]

If you could have a new look, I think I have removed most ambiguity by pointing to a single doc that is kept up-to-date by a script.

[mroderick]

This looks good 👍

I tried running npm run build locally, which didn't fail at least :)

[mroderick]

Is it necessary to disable ESLint entirely from this point on?

[fatso83]

I started just disabling the jsdoc rule, then I needed to disable another one, and then I was like: "screw it, this is just a util", but sure, I could list them.

[fatso83]

Hmm ... added the rules, but now Prettier and ESLint are fighting between themselves 😭

./node_modules/.bin/eslint --fix script/*.js will do one thing and npm run prettier:write -- will do another. That means I can get eslint content, but as soon as someone does prettier --write it will be reverted.

[fatso83]

Pushed a fix to eslint-config