Document policy for APIs that are experimental and/or not supported by all browsers

[armanbilge]

This comes up time and time again e.g. in #469. If we can determine some guidelines for this, should be easy enough to follow.

[armanbilge]

See #469 (comment), this seems like the way forward.

[japgolly]

@sjrd says:

I would suggest leaving experimental in the past, and represent instead the full spec, independently of browser support. Otherwise, there's never a good time nor a good way to have things "graduate" out of experimental anyway.

Yeah ok makes sense. So experimental goes in the bin and our API is just everything available, with the onus on users to know the availability status of the API they choose to call.

Semi-separately, I think it would be a good idea to have browser-specific packages for browser-specific API too. Eg. a chrome package with Chrome-only API. Thoughts?

[armanbilge]

Semi-separately, I think it would be a good idea to have browser-specific packages for browser-specific API too.

Interesting! What's an example of e.g. a Chrome-only API?

[japgolly]

Also, it would be good if we could somehow indicate browser support somehow though, and in a backwards-compatible way. Ideas:

• mention in ScalaDoc
• annotations
• encode in term/type names (eg. @JSName("x") def x_experimental which we then deprecate and replace over time if necessary)
• ???

None of these options seem amazing. I kind of like the annotations idea because

1. a quick look at the source is all that's needed, don't even have to really read unlike ScalaDoc
2. could be used be IDE plugins
3. super-low cost on maintenance

But is it even worth it? I weakly feel that it might be a good tradeoff. Thoughts?

[armanbilge]

If I had to choose one, I'd say annotations as well. But it seems like a lot of work to keep the statuses up-to-date?

[armanbilge]

Thinking about automation: could we query www.caniuse.com via an API to add this information programatically?

Update: cool, looks like it's all available here: https://github.com/Fyrd/caniuse

[japgolly]

Hmmm, now that I've let this simmer a bit, I think it's not worth it. Mainly because we aren't getting paid to work on this (and I personally don't have any income lol!) so although it's a nice idea, I personally don't want to spend the time on it. You wanna take this on @armanbilge or shall we close it?

(This would be good to reopen if we end up generating everything from ts.)

[armanbilge]

Agree, let's roll that idea into the mythical #487.

[japgolly]

Hahaha i actually laughed out loud at that. Look I don't know if there'll ever be an implementation for #487 but the myth will certainly be legend. 😆

[armanbilge]

In summary, the way forward #469 (comment):

I would suggest leaving experimental in the past, and represent instead the full spec, independently of browser support. Otherwise, there's never a good time nor a good way to have things "graduate" out of experimental anyway.

Decided in #514 (comment).