Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

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

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
482b774
✨ ADR for Runtime/engine/host/environment support and CI
ctcpip Apr 29, 2025
750948b
📝 clarify library support vs CI support
ctcpip Apr 29, 2025
f157948
📝 clarifications
ctcpip Apr 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 77 additions & 0 deletions docs/adr/environments-and-ci.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# ADR 35580f0d-f429-412b-acef-83655e3cab11: Runtime/engine/host/environment support and CI

## Status

Proposed

## Submitters

- @ctcpip

## Decision Owners

- @expressjs/express-tc

## 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


Several points were raised during the discussion:

- Cost of running additional CI vs the likelihood of detecting a problem
- Introducing maintenance overhead and possible coupling to other environments' development lifecycle
- No JS engine implements ECMAScript 100% correctly; thus, claiming "ES2015 support" does not guarantee correctness across all environments.
- Environment regressions or language edge cases could break functionality in unpredictable ways that are not practical for us to monitor across all environments.

## Decision

- We will **not** add non-Node.js environment testing to our CI pipelines.
- CI will continue to run only against supported Node.js versions.
- 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

- 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

applying suggestion with a small tweak

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

@ctcpip ctcpip Apr 29, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

- If issues are reported for other environments, maintainers may investigate at their discretion, but no automated validation or regression testing infrastructure will be built for them.

## Rationale

- **Alternatives Considered:**
- **Add support for additional environments in CI**: Rejected due to complexity and minimal return on value.

- **Pros and Cons**:

**Pros**:
- Keeps CI lightweight and maintainable
- Avoids implicit endorsement of non-Node.js environments
- Maintains focus on Express's design goals and core user base

**Cons**:
- Some users may misinterpret lack of other environment testing as non-support
- Manual verification may be required when bugs are reported in other environments

- **Why is this decision the best option?**
- It balances clarity, project focus, and contributor/maintainer effort. It avoids premature optimization or expanding scope into formal environment support.

## Consequences

- **Positive Impact**:
- Reduced CI runtime and maintenance burden
- Clearer expectations about what we support and test

- **Negative Impact**:
- Users of alternate environments may find compatibility issues undetected until runtime
Copy link
Member

@jonchurch jonchurch May 12, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


- **Mitigations**:
- Update README or documentation to clarify compatibility expectations and language feature dependencies
- Encourage users of alternate environments to report issues with enough detail to investigate

## Implementation

- Close PRs proposing CI additions for alternate environments unless there is strongly compelling, project-aligned justification
- Optionally, update documentation for relevant libraries to clarify assumptions

## References

- [https://test262.fyi](https://test262.fyi)
- [path-to-regexp issue on old browser support](https://github.com/pillarjs/path-to-regexp/issues/330)
- [ADR: CommonJS and ESM](https://github.com/expressjs/discussions/pull/323)