WinterCG Common key proposal

[Ethan-Arrowood]

Introduction

As runtime keys have begun being adopted for individual platforms, some developers have asked for some kind of common key indicating a package is compatible with the WinterCG Minimum Common API, and thus the package will work in any framework that is also compatible with the Minimum Common API.

The simplest solution is to add a "wintercg" key that indicates Minimum Common API compliance. However, this solution is incomplete.

Since the Minimum Common API specification can change overtime, discrepancies can form between frameworks and packages that both claim to be compliant with the standard. For example, consider ECMAScript. When a developer uses ES2020 features in their code, but the target system can only handle ES6 code, their project simply wont work. To parallel that to the Minimum Common API, imagine if the standard was to change and add a new interface. A developer then uses that new interface in their project, and expects to be able to run their project on any framework that indicates its "wintercg" compatible. Lets assume a framework hasn't been able to add that new interface yet. This developer's project will not work in that particular framework.

There are plenty more examples to demonstrate how "wintercg" key alone is insufficient, but lets move on to a better solution proposal

Proposed Solution

There are multiple pieces to this problem

• How can frameworks reliably indicate they comply with the Minimum Common API?
• How can a library or application author indicate their thing is compatible with any framework that complies with the Minimum Common API?
• How can tools check at build-time and run-time that a given library or application is compatible with current framework?

How can frameworks reliably indicate they comply with the Minimum Common API?

Browser have had a solution to this for a long time, web platform tests. If we create a similar test suite for the Minimum Common API (and maybe even use the existing WPT), frameworks can automatically test themselves against it and report the results to a public tool such as caniuse.com.

How can a library or application author indicate their thing is compatible with any framework that complies with the Minimum Common API?

Given the usage example in the Runtime Keys specification, libraries and applications can use the "engines" fields in package.json to indicate what framework version (or version range) they can be used in. By introducing a "wintercg" key as well as versioning methodology for that represents compliance with the Minimum Common API, projects could specify exactly what version of the specification they are compliant with.

How can tools check at build-time and run-time that a given library or application is compatible with current framework?

Incorporating the versioning methodology into the test suite compliance tool, build-time and run-time tooling can be instrumented to compare values between what specified in a project’s configuration file (like package.json) with what has been publicly recorded and verify if the given project is supported.

Versioning Methodology

This part of the proposal is where I believe much of the debate will be. Two options are provided to start the discussion. Please feel free to provide more options for consideration.

Option 1: Annual versioning

• Works like ECMAScript
• At the beginning of the year, we release “WinterCG Minimum Common API ”, for example “WinterCG Minimum Common API 2023”
• Throughout the remainder of the year, changes are added to a “next” version of the spec.
• Keys could look like wintercg-2023 and wintercg-next
• But when used in something like engines, they may be used like "wintercg": "2023" instead
• For 2023 specifically, we would work to solidify and release the current spec as. And then we’d start the annual release format starting in 2024.

Option 2: semver

• Works like many of the frameworks do
• Breaking changes are included in Major versions
• New features are included in Minor versions
• Fixes are included in Patch versions
• Keys could look like wintercg-1.0.0 and wintercg-2.3.4
• Similar to annual model, they keys could also be used like "wintercg": "1.0.0"

Next Steps

Thank you for reading this proposal. Please comment your thoughts and feedback in this issue thread or in the WinterCG Matrix channel. We will discuss this proposal at the next WinterCG call on May 4th, 2023. It will also be presented during my talk at Open Source Summit on May 10th. 🚀

[styfle]

Keys could look like wintercg-2023 and wintercg-next

Why does the key need to change?

Wouldn't the key remain the same (wintercg) and only the value change (2023)?

Something like:

{
  "engines": {
    "wintercg": ">=2023"
  }
}

[danielroe]

Hey 👋 I'm working on Nitro with @pi0. We often face the issue where libraries are packaged to assume that the node export condition is the 'server build' of a library. (For example, in the Vue ecosystem, this build will be the one built to avoid sharing objects across requests, or that doesn't include the browser devtools dependency.) When building for runtimes that are not node-based, we are thus forced currently to pick the node subpath export and polyfill any node-specific dependencies.

Ideally I'd like to see a different export condition that can describe an environment with access to Web APIs but not necessarily a browser (worker? web?).

Naturally, I think WinterCG would be a good place to discuss and start to build consensus on this. Could we use the common key in subpath exports?

{
  "name": "pkg",
  "exports": {
    ".": {
      "node": "./dist/pkg.node.mjs",
      "wintercg": "./dist/pkg.worker.mjs",
      "import": "./dist/pkg.mjs"
    }
  }
}

Having said that, adoption is crucial for this if it will be adopted by library maintainers, and I worry that wintercg might not be generic enough in this context (subpath exports).

Thoughts very welcome.

[Ethan-Arrowood]

I've been thinking about the scenario of how the key may be used in the exports field. In particular, what if I need to specify one export for wintercg v2023 and one export for wintercg v2024?

I've come to the conclusion that this feels like a non-problem. Tooling currently doesn't support multiple exports for different runtime versions. And in the wild, when there's a major difference in a library based on the runtime version (lets say Node.js v14 vs Node.js v20), then the library will maintain two release lines (usually two major versions of the library itself) that have two distinct source branches too.

So really exports > wintercg > is fine as it'll act just like existing keys there. If for some reason the library needs to support multiple wintercg minimum common api versions, then they will need to maintain two release lines (whatever that might mean for them)

[styfle]

MDN just announced Baseline which is basically a minimum common API for the web. I wonder if there is any insight we can glean from their solution that could help here. Seems like there are planning to use years as versions like Baseline 2024.