✨ ADR for Runtime/engine/host/environment support and CI

[ctcpip]

No description provided.

[blakeembrey]

The consequence here isn't true of path-to-regexp, where it was instead redundant, but overall LGTM.

[ctcpip]

yeah, happy to capture that if you have a concrete suggestion, but this is just some background context to set the stage, and don't want to risk comprehension with potentially excessive qualification and detail at this point

[blakeembrey]

Express and its libraries were originally designed to run on Node.js (V8). While some libraries can run in other environments (e.g. runtimes, engines, browsers), intentionally or not, they are not necessarily supported everywhere. Consequently, our CI systems do not include other environments as part of their testing workflows.

Honestly it looks fine already, and I think the comment about maintenance below covers the realities of path-to-regexp.

[blakeembrey]

Suggested change

	- Libraries will not explicitly list all supported environments; they may, however, state general compatibility information, e.g. ECMAScript version.
	- Libraries may state general compatibility information, e.g. ECMAScript version, and optionally include information about supported environments but will not explicitly list all supported environments

It was probably fine before, just reversing the order a bit since I think it's what you're getting at (e.g. state support generally, but don't waste time enumerating everything in the world).

[ctcpip]

applying suggestion with a small tweak

[ctcpip]

I'm making the change but I am apprehensive about "include information about supported environments". I explicitly do not want to be in the business of listing specific runtimes, engines, etc.

[blakeembrey]

I agree. I wanted to find a way to capture "this thing should run on Safari 10 just fine" without promising the world, so if there's a better way to phrase it that'd be great. Not everyone reads ES2015 or "uses generators and classes" and goes "ah, Safari 10".

[blakeembrey]

Working backward, I think a sentence I'd write for path-to-regexp is something like:

Supports ES2015 runtimes such as Node X+, Deno, Bun, Chrome, Safari X+, etc.

That's already a mouthful but hopefully it makes sense. I do want someone to legitimately feel happy knowing Safari issues would be fixed if they found an issue and not closed because ES blah blah.

[ctcpip]

yeah, it's fine. the risk here is that we also don't want to be overly prescriptive on content. but it would be great if someone had an idea to capture this spirit better. maybe something will come to mind later

[ctcpip]

Supports ES2015 runtimes such as Node X+, Deno, Bun, Chrome, Safari X+, etc.

hmmm, this is precisely what I'd like to avoid 😅

edit: but not a blocker for me, and interested in other folks thoughts as well

[blakeembrey]

Perhaps it's more "general compatibility information, e.g. ECMAScript version, or environment requirements"? You're right, I shouldn't enumerate the environments but instead want a general statement about what environments should work.

I don't have a solid statement that I want to actually work backward from here. I'm trying to think of these two cases:

1. A simple no-environment specific library that may want to say "supports ES2015 and strives to support the last X years of popular browsers".
2. A library that supports X and Y explicitly, e.g. by using native packages such as node:http.

[blakeembrey]

I was overthinking the "but people might not know what environments support ES2015".

[ctcpip]

you could always link to the compat table. e.g, for ES2015/ES6: https://compat-table.github.io/compat-table/es6/