wintercg / runtime-keys Goto Github PK

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. 🚀

A lot of times I encounter the need to single a specific runtime out. For instance, all wintercg runtimes meet my criteria except node.

What I'm looking for is key setup which allows me to put specific runtimes infront of a wintercg catchall.

Can browser service worker runtime be included?

Hono can run in Node, Deno, Bun, Cloudflare Workers, Pages, and can also run in a service worker to power an offline web app.

I'd like to see more things target/support service workers too (e.g. Next.js, Deno Fresh, and HonoX could all be made to work in various runtime environments and could then easily be ran in a service worker).