Compatibility and Interop Specification (Versioning WCs)

Overview

As "Web Components" itself is an umbrella label for a subset of web standards, yet also benefits from and is enhanced by many other adjacent web standards, coalescing around a shared understanding of what it means to be a "Web Component" can be a bit challenging from a user (of WCs) perspective. This extends to characteristics of a Web Component like the spec web platform features used, bundling, polyfills, or server rendering support to name a few. Additionally, it is often up to each maintainer / platform / project to try and best explain the journey of developing and distributing Web Components so as to best facilitate that user (developer) journey for their respective use case.

Motivation

For example, for a new major version release of most large and popular open source project, I can go to a changelog or blog post and typically get a run down of:

Features and capabilities
Environment and runtime expectations
Potential known issues and limitations

By taking a sample of what's standard in the platform through a representative majority of critical browsers (Chrome / Edge, Firefox, Safari) at a given time, the goal of this proposal would be in the (ongoing) drafting of a living specification document that can identify a reasonable "SLA" that community projects can align on, either directly documented in a project's README / website, or through something like Custom Elements Manifest.

Use Cases

There are a couple principal use cases that come to mind as for who might best be able to take advantage of such a protocol for Web Components.

Library Authors

Library authors wanting to know what features are "safe" to use or adopt, and that can reference via a link for evaluators or potential consumers to communicate what sort of features they take advantage of from the web platform or to what degree of polyfills or shims may be expected from the userland implementor. Being able to express this through a link that could provide supporting references and materials to help users achieve the necessary parity to instrument said library would be very useful.

It can also be used to hint or indicate to any sort of SSR compatibility.

(Full Stack) Framework Implementors

For those delivering frameworks solutions where SSG or SSR comes into play, this would really benefit by aligning on a shared understanding of the WC related APIs, on top of the runtime at play. I know from observing a handful of various repos on GitHub that using WCs in non-tuned for WCs SSR frameworks can often come with unexpected results, so adding a little more standardization on the server side could be really valuable.

In a way, this feels like a natural extension from the ElementRender proposal presented in the SSR issue.

Specification

Similar to how TC39 drafts a new version of the ECMAScript specification each year to set a level of expectation, the Web Components community could similarly draft as well, and help capture what features or standards have broad enough platform support that they can be "versioned" against.

Documentation

So at pre-defined intervals the governing body would "snap a line" of what is supported by browser vendors at that given time and "tag" that new level of cross-platform support as a new version, and then publish those details. Each new entry published would be a canonical link that could be reference in Custom Elements Manifest, thus clearly communicating a level of support and / or compatibility.

Version	Year	Standards Adopted	Notes
2	TBD	TBD	Evaluating import assertions and constructible stylesheets
1	2021	Custom Elements, HTML Templates, Shadow DOM, ESM	Baseline

Custom Elements Manifest

Totally bike-shedding on the name here with specificationVersion but an example snippet from a custom-elements-manifest.json would be defined as such, e.g.

{
  "schemaVersion": "1.0.0",
  "specificationVersion": "v2",
  "readme": "README.md",
  "modules": [
    "..."
  ]
}

Canonical link would be evaluated to something like http://webcomponents.org/community-specification/v2.html.

### Server Side Rendering (SSR) I see something like this being especially valuable for SSR frameworks, so as to allow each of them to set and support the level of compatibility with any of these versions that they can support. For user's of these frameworks, it would be a very helpful reference of what sort of baseline support to expect as they're picking their frontend libraries / design systems / etc. For example, thinking of these kinds of APIs (and to what degree of support if applicable) that might be assumed already given a browser context and so would want special attention for SSR: - `window` / `document` - `customElements.[define|get]` - `HTMLElement` - `addEventListener` (no-op?) - `HTMLTemplateElement` - `attachShadow` - `.[get|set|has]Attribute` - `

webcomponents-cg / community-protocols