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 all 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
78 changes: 78 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,78 @@
# 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.
- Exceptions may be made iff there is strongly compelling, project-aligned justification.
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
- Exceptions may be made iff there is strongly compelling, project-aligned justification.
- Exceptions may be made if there is strongly compelling, project-aligned justification.

Copy link
Member Author

Choose a reason for hiding this comment

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

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

Copy link
Member

Choose a reason for hiding this comment

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

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

Either way, lets merge the suggestion right?

- 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.
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.
Comment on lines +31 to +33
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
- 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.

Copy link
Member Author

Choose a reason for hiding this comment

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

intent is to deliberately avoid mentioning specific environments

Copy link
Member Author

Choose a reason for hiding this comment

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

#365 (comment)

Copy link
Member

Choose a reason for hiding this comment

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

edited out the mention

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


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