doc: explanation about flagged feature etiquette needed

[devsnek]

There is a lot of misunderstanding in the ecosystem about how harmony* and experimental flags should be used, most alarmingly in the case of libraries that ship support for features that are flagged.

We need to document:

• Why flags are how we (and V8*) ship experimental features
• Why you should only use flagged features at an application level
• Why you shouldn't use flagged features in production environments
• Why you shouldn't publish versions of your libraries with support for flagged features
• Given the restrictions above, ways that you can help us test flagged features

This seems like a lot for one person so I thought I would open an issue about it and get some collaboration going.

*We probably shouldn't document V8's flagging, but it might be necessary to at least mention harmony flags.

[TimothyGu]

See also https://nodejs.org/en/docs/es6/.

[AdityaSrivast]

@devsnek I want to work on this issue. Can you tell me what is to be done, please?

[devsnek]

@AdityaSrivast pretty much just compositing the points in my comment and the link Timothy sent. I think introducing a replacement of that es6 page might be the best option here.

[AdityaSrivast]

@devsnek There's a problem. I don't know the answer to these questions 😅 Is there still any way I can fix it, please?

[Trott]

Maybe we can get this moving a bit by scaling back what we hope to document, at least on the first pass. Here's the list initially proposed by @devsnek but with a lot of the "why" stuff changed to simply documenting that's-the-way-it-is.

• Only use flagged features at an application level.
  • What does "application level" mean here?
• Do not use flagged features in production environments.
• Do not publish versions of your libraries with support for flagged features.
  • Should we simplify to "do not publish libraries that rely on flagged features (perhaps except when such modules are explicitly experimental/unstable/not-for-production themselves?)"
• Given the restrictions above, ways that you can help us test flagged features.
  • This is the task on this checklist that needs the most effort/attention.