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

ctcpip · 2025-04-29T21:02:50Z

No description provided.

docs/adr/environments-and-ci.md

blakeembrey · 2025-04-29T21:24:59Z

docs/adr/environments-and-ci.md

+
+## Context
+
+Express and its libraries were specifically designed to run with Node.js (V8). While some of our libraries can run in other environments (e.g. runtimes, engines, browsers), they are not necessarily supported in all environments. Consequently, our CI systems do not include other environments as part of their testing workflows.


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

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

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.

docs/adr/environments-and-ci.md

blakeembrey · 2025-04-29T21:29:13Z

docs/adr/environments-and-ci.md

+- Support for other environments may exist, but we do not guarantee correctness or compatibility across all environments.
+  - Some libraries, particularly language-only libraries which do not require non-language APIs, strive to support as many environments as possible.
+    - Nonetheless, support is not guaranteed across every possible environment, and is provided on a best-effort basis.
+  - Libraries will not explicitly list all supported environments; they may, however, state general compatibility information, e.g. ECMAScript version.


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

applying suggestion with a small tweak

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.

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

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.

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

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

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:

A simple no-environment specific library that may want to say "supports ES2015 and strives to support the last X years of popular browsers".

A library that supports X and Y explicitly, e.g. by using native packages such as node:http.

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

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

docs/adr/environments-and-ci.md

Co-authored-by: Blake Embrey <[email protected]>

UlisesGascon · 2025-05-07T20:36:42Z

docs/adr/environments-and-ci.md

+## Decision
+
+- We will **not** add non-Node.js environment testing to our CI pipelines.
+  - Exceptions may be made iff there is strongly compelling, project-aligned justification.


Suggested change

- Exceptions may be made iff there is strongly compelling, project-aligned justification.

- Exceptions may be made if there is strongly compelling, project-aligned justification.

https://en.wiktionary.org/wiki/iff 🙂

Ok I am confused, is this intentional or an etymology joke 😆 ?

Either way, lets merge the suggestion right?

UlisesGascon

LGTM!

jonchurch · 2025-05-12T21:40:48Z

docs/adr/environments-and-ci.md

+- Support for other environments may exist, per maintainer discretion, but we do not guarantee support across all environments.
+  - Some libraries, particularly language-only libraries which do not require non-language APIs, strive to support as many environments as possible.
+    - Nonetheless, support is not guaranteed across every possible environment, and is provided on a best-effort basis.


Suggested change

- Support for other environments may exist, per maintainer discretion, but we do not guarantee support across all environments.

- Some libraries, particularly language-only libraries which do not require non-language APIs, strive to support as many environments as possible.

- Nonetheless, support is not guaranteed across every possible environment, and is provided on a best-effort basis.

- Some Express libraries may work in other environments, but we do not guarantee compatibility or prioritize testing and development for them. Support outside Node.js is best-effort and may vary between packages, depending on maintainer interest and alignment with project goals.

- Some libraries, particularly language-only libraries which do not require non-language APIs, strive to support as many environments as possible.

intent is to deliberately avoid mentioning specific environments

#365 (comment)

edited out the mention

jonchurch · 2025-05-12T21:42:15Z

docs/adr/environments-and-ci.md

+  - Clearer expectations about what we support and test
+
+- **Negative Impact**:
+  - Users of alternate environments may find compatibility issues undetected until runtime


Suggested change

- Users of alternate environments may find compatibility issues undetected until runtime

- Users of alternate environments may find that Express libraries appear to work but fail under certain conditions due to untested APIs or platform differences. This may result in runtime issues that are not prioritized for triage or resolution unless clearly aligned with the project’s goals.

jonchurch · 2025-05-12T21:44:28Z

docs/adr/environments-and-ci.md

+
+## Context
+
+Express and its libraries were specifically designed to run with Node.js (V8). While some of our libraries can run in other environments (e.g. runtimes, engines, browsers), they are not necessarily supported in all environments. Consequently, our CI systems do not include other environments as part of their testing workflows.


Suggested change

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

Express and its libraries were specifically designed to run with Node.js (V8). While some of our libraries can run in other environments (e.g. runtimes, engines, browsers), they are not necessarily supported in all environments—that is, we do not test against them, optimize for them, or guarantee compatibility. Consequently, our CI systems do not include other environments as part of their testing workflows.

jonchurch

looks good as is, my suggestions are aimed to make it harder for someone to read this and conclude "I cannot use express in these environments"

wesleytodd

Comments are only nit-picks. Generally 👍 on merging even if we do not address the nits.

wesleytodd · 2025-05-13T15:04:51Z

docs/adr/environments-and-ci.md

+
+## Context
+
+Express and its libraries were specifically designed to run with Node.js (V8). While some of our libraries can run in other environments (e.g. runtimes, engines, browsers), they are not necessarily supported in all environments. Consequently, our CI systems do not include other environments as part of their testing workflows.


To disambiguate a bit from "version" and hopefully make it more clear why that is relevant in this ADR:

Suggested change

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

Express and its libraries were specifically designed to run with Node.js (and the V8 JavaScript Engine). While some of our libraries can run in other environments (e.g. runtimes, engines, browsers), they are not necessarily supported in all environments. Consequently, our CI systems do not include other environments as part of their testing workflows.

wesleytodd · 2025-05-13T15:07:53Z

docs/adr/environments-and-ci.md

+## Decision
+
+- We will **not** add non-Node.js environment testing to our CI pipelines.
+  - Exceptions may be made iff there is strongly compelling, project-aligned justification.


Ok I am confused, is this intentional or an etymology joke 😆 ?

Either way, lets merge the suggestion right?

wesleytodd · 2025-05-13T15:10:06Z

docs/adr/environments-and-ci.md

+  - Exceptions may be made iff there is strongly compelling, project-aligned justification.
+- CI will continue to run only against supported Node.js versions.
+- Support for other environments may exist, per maintainer discretion, but we do not guarantee support across all environments.
+  - Some libraries, particularly language-only libraries which do not require non-language APIs, strive to support as many environments as possible.


Hoping this language may be more clear? I did not understand at first what "language-only" meant and it took a few reads for me to be sure.

Suggested change

- Some libraries, particularly language-only libraries which do not require non-language APIs, strive to support as many environments as possible.

- Some libraries, particularly libraries which do not require non-ECMA APIs (Node.js apis, WHATWG apis, etc), strive to support as many environments as possible.

wesleytodd · 2025-05-13T15:10:47Z

docs/adr/environments-and-ci.md

+  - Some libraries, particularly language-only libraries which do not require non-language APIs, strive to support as many environments as possible.
+    - Nonetheless, support is not guaranteed across every possible environment, and is provided on a best-effort basis.
+  - Libraries may state general compatibility information, e.g. ECMAScript version, and possibly information about supported environments, but will not explicitly list all supported environments.
+- If issues are reported for other environments, maintainers will investigate at their discretion.


Suggested change

- If issues are reported for other environments, maintainers will investigate at their discretion.

- If issues are reported for other environments, maintainers may investigate at their discretion.

ctcpip requested a review from a team April 29, 2025 21:02

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

482b774

ctcpip force-pushed the env-ci branch from 5aa21b3 to 482b774 Compare April 29, 2025 21:03

ctcpip added tc agenda top priority Issues which the TC deem our current highest priorities for the project labels Apr 29, 2025

bjohansebas approved these changes Apr 29, 2025

View reviewed changes

📝 clarify library support vs CI support

750948b

blakeembrey reviewed Apr 29, 2025

View reviewed changes

📝 clarifications

f157948

Co-authored-by: Blake Embrey <[email protected]>

This was referenced Apr 30, 2025

2025-05-07 Express Working Session #368

Closed

2025-05-12 Express TC Meeting #370

Closed

UlisesGascon reviewed May 7, 2025

View reviewed changes

UlisesGascon approved these changes May 7, 2025

View reviewed changes

jonchurch reviewed May 12, 2025

View reviewed changes

jonchurch approved these changes May 12, 2025

View reviewed changes

wesleytodd approved these changes May 13, 2025

View reviewed changes

This was referenced May 15, 2025

2025-05-21 Express Working Session #374

Closed

2025-05-26 Express TC Meeting #383

Closed

github-actions bot mentioned this pull request May 29, 2025

2025-06-04 Express Working Session #385

Open


		## Context

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

	- 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

	- Exceptions may be made iff there is strongly compelling, project-aligned justification.
	- Exceptions may be made if there is strongly compelling, project-aligned justification.

	- Users of alternate environments may find compatibility issues undetected until runtime
	- Users of alternate environments may find that Express libraries appear to work but fail under certain conditions due to untested APIs or platform differences. This may result in runtime issues that are not prioritized for triage or resolution unless clearly aligned with the project’s goals.

	- Some libraries, particularly language-only libraries which do not require non-language APIs, strive to support as many environments as possible.
	- Some libraries, particularly libraries which do not require non-ECMA APIs (Node.js apis, WHATWG apis, etc), strive to support as many environments as possible.

	- If issues are reported for other environments, maintainers will investigate at their discretion.
	- If issues are reported for other environments, maintainers may investigate at their discretion.

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

Are you sure you want to change the base?

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

Uh oh!

Conversation

ctcpip commented Apr 29, 2025

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ctcpip Apr 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

UlisesGascon left a comment

Choose a reason for hiding this comment

Uh oh!

jonchurch May 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jonchurch May 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jonchurch left a comment

Choose a reason for hiding this comment

Uh oh!

wesleytodd left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ctcpip Apr 29, 2025 •

edited

Loading

jonchurch May 12, 2025 •

edited

Loading

jonchurch May 12, 2025 •

edited

Loading

wesleytodd left a comment •

edited

Loading