Ability to mark new components as "experimental"

[dylanjha]

There's some instances where we build components and I think would benefit from getting to use them in the wild before officially stamping them and making them subject to SemVer breaking change guidelines.

In the past, we've done things like build components directly into Mux Player to test them out, tweak them, etc. before extracting them into Media Chrome. That can be a good path, but the downside is that for that period of time it lives as an internal thing in Mux Player and we don't get input from other folks using Media Chrome.

The way I could imagine this working is:

• Mark it as experimental in docs with an orange callout at the top like: This component is experimental, if you're using it we'd love your feedback. The API for this component might change before it is released as non-experimental (can probably improve the wording there, but you get the idea). Can also add a exp orange tag on the component in the side nav
• Add a console.log in the constructor with a message This component is experimental, see docs for more details [link to docs for this component] (I actually probably wouldn't want to do this because it would add noise in the console for folks using MC, but it's a decision we could make)

This would help us:

• In Mux Player to use MC components instead of siloing them inside Mux Player
• Allow others to use experimental MC components and provide feedback & ideas for improvement
• Allow us to move faster by releasing components when there's still a few outstanding questions on some specific APIs or implementation details

How this could go bad:

• We release a bunch of experimental components and never upgrade them to non-experimental. That would be sloppy and bad for the project
• We get too liberal with marking components as "experimental" when they're actually just not good enough yet and they need more work

I think today we might want to mark <media-captions-menu-button> as experimental because we have this new issue that came up around allowing application-level styles to be applied to components that are nested in the shadow DOM (@gkatsev will open a separate issue/discussion about that). Depending on where we land on that discussion, the API and structure of <media-captions-menu-button> might have to change.

[gkatsev]

Prior art for "experminal"/stability index: https://nodejs.org/dist/latest-v18.x/docs/api/documentation.html#stability-index

[heff]

I feel ok with where we landed in the IRL conversation, which I understood as:

• Experimental components will not be included in the default MC bundle
• There will be an EXPERIMENTAL directory or equivalent where experimental components can be optionally included from
• It should be expected that experimental components will break between versioned releases (including patch). So either don't include them in production builds, or manually upgrade each new media chrome version and intentionally test those components in the process.
• All possible steps will be taken in docs to educate on the experimental component versioning exception, to avoid blind use of them.

@dylanjha's notes on marking it experimental in docs make sense to me. And probably not in the console. If we can ever tell they're using the component in an outdated way we could add a log note then.

[dylanjha]

This sounds good. @gkatsev will you be able to handle these two pieces either as part of the <media-captions-menubutton> work, or as a follow-up?

There will be an EXPERIMENTAL directory or equivalent where experimental components can be optionally included from
All possible steps will be taken in docs to educate on the experimental component versioning exception, to avoid blind use of them.

[gkatsev]

#464