From 482b774edb5fe56d01e6e3728b22a3d077e8f06e Mon Sep 17 00:00:00 2001 From: ctcpip Date: Tue, 29 Apr 2025 16:02:25 -0500 Subject: [PATCH 1/3] =?UTF-8?q?=E2=9C=A8=20ADR=20for=20Runtime/engine/host?= =?UTF-8?q?/environment=20support=20and=20CI?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/adr/environments-and-ci.md | 74 +++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 docs/adr/environments-and-ci.md diff --git a/docs/adr/environments-and-ci.md b/docs/adr/environments-and-ci.md new file mode 100644 index 0000000..d2247aa --- /dev/null +++ b/docs/adr/environments-and-ci.md @@ -0,0 +1,74 @@ +# 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 officially supported. 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. +- Engine 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. +- Unofficial support for other environments may exist, but we do not guarantee correctness or compatibility across those environments. +- 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 + +- **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) From 750948b10ac136ddba49ee8169306a868fbb3427 Mon Sep 17 00:00:00 2001 From: ctcpip Date: Tue, 29 Apr 2025 16:22:09 -0500 Subject: [PATCH 2/3] =?UTF-8?q?=F0=9F=93=9D=20clarify=20library=20support?= =?UTF-8?q?=20vs=20CI=20support?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/adr/environments-and-ci.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/adr/environments-and-ci.md b/docs/adr/environments-and-ci.md index d2247aa..480cdfb 100644 --- a/docs/adr/environments-and-ci.md +++ b/docs/adr/environments-and-ci.md @@ -14,20 +14,23 @@ Proposed ## 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 officially supported. 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. 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. -- Engine regressions or language edge cases could break functionality in unpredictable ways that are not practical for us to monitor 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. -- Unofficial support for other environments may exist, but we do not guarantee correctness or compatibility across those environments. +- 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. - 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 From f15794805383b6b0ee751d2fde3f009bb804c4c2 Mon Sep 17 00:00:00 2001 From: ctcpip Date: Tue, 29 Apr 2025 16:58:07 -0500 Subject: [PATCH 3/3] =?UTF-8?q?=F0=9F=93=9D=20clarifications?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Blake Embrey --- docs/adr/environments-and-ci.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/adr/environments-and-ci.md b/docs/adr/environments-and-ci.md index 480cdfb..30bc7d3 100644 --- a/docs/adr/environments-and-ci.md +++ b/docs/adr/environments-and-ci.md @@ -26,12 +26,13 @@ Several points were raised during the discussion: ## 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. - 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. +- 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. - - Libraries will not explicitly list all supported environments; they may, however, state general compatibility information, e.g. ECMAScript version. -- 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. + - 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. ## Rationale