From 150e5e8d14654c6433ffcaa7dc894ac5b1fe2d3b Mon Sep 17 00:00:00 2001 From: Titus Fortner Date: Thu, 2 Jul 2026 07:31:29 -0500 Subject: [PATCH 1/4] [adr] Selenium Manager released API --- .../selenium-manager-released-api.md | 85 +++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 docs/decisions/selenium-manager-released-api.md diff --git a/docs/decisions/selenium-manager-released-api.md b/docs/decisions/selenium-manager-released-api.md new file mode 100644 index 0000000000000..bbd0f5085c15d --- /dev/null +++ b/docs/decisions/selenium-manager-released-api.md @@ -0,0 +1,85 @@ +# Selenium Manager ships as an official, independently released tool + +- Status: Proposed +- Discussion: _PR pending_ + +## Context + +Releasing Selenium Manager (SM) independently of the bindings means a binding and the SM it +invokes can differ in version. This record settles what that commits us to. A decision belongs +here only if it either cannot change after 1.0 without a breaking change — the forward-compatibility +behavior and every committed default — or is an obligation the independent release itself creates. +Bugs and additive enhancements (new browsers, telemetry fixes, warning wording) are out of scope. + +## Decision + +**Versioning and distribution.** SM takes its own semantic version from `1.0.0` and is released +standalone as well as bundled. Bindings ship and default to a known-good SM, but already let a user +point at a different binary, so a binding and the SM it runs may differ in version. + +**Output.** The default follows standard CLI convention — result on stdout, logs on stderr — so +`$(selenium-manager …)` captures only the result. Bindings set `--output` explicitly and are +unaffected, so only the standalone audience is impacted. + +**Forward compatibility.** Neither the bindings nor the binary may fail solely because of version +skew. How an older SM treats an input it does not recognize depends on the input: + +- *Unknown switch* → warn (tell the user to update SM) and ignore; the binding still gets valid + paths. A switch only adjusts resolution, so dropping it is safe. +- *Unknown value of a switch that has a default* (output format, log level) → use the default and warn. +- *Unknown value of a switch with no default* → error, naming the value and telling the user to + update SM (e.g. `Selenium Manager 1.2 does not support browser 'chrome-for-testing'`). There is + nothing to fall back to; for `--browser` these are distinct browsers where substituting one would + be the wrong result. Erroring is safe because such values are only ever opt-in. +- New switches must be optional — an older binding will omit them. +- Nothing in the contract — switches, values, output fields — is removed or renamed without a + deprecation cycle. +- Current defaults must not change once released, and must all be documented + ([configuration reference](https://www.selenium.dev/documentation/selenium_manager/#configuration)). + +**Resolution.** + +- When provided a driver location, SM validates the correct browser and downloads it if necessary, + instead of being bypassed. This is not backward compatible, so a toggle is necessary to control + desired behavior. +- A `PATH` driver whose version does not match the browser is not used; SM fetches a matching one. + +**Telemetry.** + +- Data is collected by default and can be disabled. It is anonymous and holds no PII, but SM makes a + best effort to inform users: run from an interactive session it prompts on first use and stores the + result; run non-interactively it emits a clear `WARN` with what data is sent and how to disable it. +- The binding must pass in the Selenium version and language (name and version). +- SM must pass in the SM version. + +## Considered options + +- **Leaving Beta.** + - Stay in Beta — contract stays mutable. + - Drop the label but keep versioning coupled to the bindings — empty releases, no standalone use. + - Independently versioned, standalone-released — **selected**. +- **Default `--output`.** + - Keep `logger` — log lines on stdout pollute `$(selenium-manager …)`. + - `mixed` — result on stdout, logs on stderr; bindings set it explicitly, so are unaffected — **selected**. +- **Unknown switch, or unknown value of a switch with a default.** + - Error — turns expected skew into a broken session. + - Warn and ignore the switch, or use the default value — **selected**. +- **Unknown value of a switch with no default** (e.g. `--browser`). + - Warn and substitute a fallback — silently does something other than what was asked. + - Error, directing the user to update SM — **selected**. +- **A provided driver.** + - Keep bypassing SM — the browser is left unmanaged. + - Always run SM — breaks backward compatibility. + - Run it behind a toggle, default unchanged — **selected**. +- **A mismatched `PATH` driver.** + - Use it with a warning — usually still fails at session start. + - Do not use it, fetch a matching one — **selected**. +- **Telemetry consent.** + - Silent opt-out everywhere — weak for a released tool. + - Opt-in everywhere — the binding path collects nothing. + - Opt-out with a notice when bundled, opt-in when standalone — **selected**. + +## Consequences + +- Once released, the contract constrains every `rust/` change: no switch, value, or output field + changes without a deprecation cycle, and the current defaults are locked. From b59bb22c3292fdb3b717fbd702bf76d93d65c4e3 Mon Sep 17 00:00:00 2001 From: Titus Fortner Date: Thu, 2 Jul 2026 07:32:52 -0500 Subject: [PATCH 2/4] [adr] number record to PR 17741 --- ...released-api.md => 17741-selenium-manager-released-api.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename docs/decisions/{selenium-manager-released-api.md => 17741-selenium-manager-released-api.md} (97%) diff --git a/docs/decisions/selenium-manager-released-api.md b/docs/decisions/17741-selenium-manager-released-api.md similarity index 97% rename from docs/decisions/selenium-manager-released-api.md rename to docs/decisions/17741-selenium-manager-released-api.md index bbd0f5085c15d..27b3a4549f2e2 100644 --- a/docs/decisions/selenium-manager-released-api.md +++ b/docs/decisions/17741-selenium-manager-released-api.md @@ -1,7 +1,7 @@ -# Selenium Manager ships as an official, independently released tool +# 17741. Selenium Manager ships as an official, independently released tool - Status: Proposed -- Discussion: _PR pending_ +- Discussion: https://github.com/SeleniumHQ/selenium/pull/17741 ## Context From fc5a3b116e1e1bac04cd75e9143b53c6f6071046 Mon Sep 17 00:00:00 2001 From: Titus Fortner Date: Thu, 2 Jul 2026 10:05:02 -0500 Subject: [PATCH 3/4] [adr] telemetry version fields and notify on send --- .../decisions/17741-selenium-manager-released-api.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/docs/decisions/17741-selenium-manager-released-api.md b/docs/decisions/17741-selenium-manager-released-api.md index 27b3a4549f2e2..4a08ec5d14086 100644 --- a/docs/decisions/17741-selenium-manager-released-api.md +++ b/docs/decisions/17741-selenium-manager-released-api.md @@ -9,7 +9,7 @@ Releasing Selenium Manager (SM) independently of the bindings means a binding an invokes can differ in version. This record settles what that commits us to. A decision belongs here only if it either cannot change after 1.0 without a breaking change — the forward-compatibility behavior and every committed default — or is an obligation the independent release itself creates. -Bugs and additive enhancements (new browsers, telemetry fixes, warning wording) are out of scope. +Bugs and additive enhancements (new browsers, warning wording) are out of scope. ## Decision @@ -30,7 +30,7 @@ skew. How an older SM treats an input it does not recognize depends on the input - *Unknown value of a switch with no default* → error, naming the value and telling the user to update SM (e.g. `Selenium Manager 1.2 does not support browser 'chrome-for-testing'`). There is nothing to fall back to; for `--browser` these are distinct browsers where substituting one would - be the wrong result. Erroring is safe because such values are only ever opt-in. + be the wrong result. Erroring is safe because such values are only ever requested explicitly. - New switches must be optional — an older binding will omit them. - Nothing in the contract — switches, values, output fields — is removed or renamed without a deprecation cycle. @@ -46,11 +46,9 @@ skew. How an older SM treats an input it does not recognize depends on the input **Telemetry.** -- Data is collected by default and can be disabled. It is anonymous and holds no PII, but SM makes a - best effort to inform users: run from an interactive session it prompts on first use and stores the - result; run non-interactively it emits a clear `WARN` with what data is sent and how to disable it. - The binding must pass in the Selenium version and language (name and version). - SM must pass in the SM version. +- Each time SM sends data, it logs what was sent and how to disable it. ## Considered options @@ -74,10 +72,6 @@ skew. How an older SM treats an input it does not recognize depends on the input - **A mismatched `PATH` driver.** - Use it with a warning — usually still fails at session start. - Do not use it, fetch a matching one — **selected**. -- **Telemetry consent.** - - Silent opt-out everywhere — weak for a released tool. - - Opt-in everywhere — the binding path collects nothing. - - Opt-out with a notice when bundled, opt-in when standalone — **selected**. ## Consequences From 3824f55c419c7a57840193ad0019b2596fb741fa Mon Sep 17 00:00:00 2001 From: Titus Fortner Date: Fri, 3 Jul 2026 11:53:09 -0500 Subject: [PATCH 4/4] [adr] decouple output decision from --output modes --- docs/decisions/17741-selenium-manager-released-api.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/decisions/17741-selenium-manager-released-api.md b/docs/decisions/17741-selenium-manager-released-api.md index 4a08ec5d14086..1a74cd26ec64e 100644 --- a/docs/decisions/17741-selenium-manager-released-api.md +++ b/docs/decisions/17741-selenium-manager-released-api.md @@ -18,7 +18,7 @@ standalone as well as bundled. Bindings ship and default to a known-good SM, but point at a different binary, so a binding and the SM it runs may differ in version. **Output.** The default follows standard CLI convention — result on stdout, logs on stderr — so -`$(selenium-manager …)` captures only the result. Bindings set `--output` explicitly and are +`$(selenium-manager …)` captures only the result. Bindings request output explicitly and are unaffected, so only the standalone audience is impacted. **Forward compatibility.** Neither the bindings nor the binary may fail solely because of version @@ -56,9 +56,9 @@ skew. How an older SM treats an input it does not recognize depends on the input - Stay in Beta — contract stays mutable. - Drop the label but keep versioning coupled to the bindings — empty releases, no standalone use. - Independently versioned, standalone-released — **selected**. -- **Default `--output`.** - - Keep `logger` — log lines on stdout pollute `$(selenium-manager …)`. - - `mixed` — result on stdout, logs on stderr; bindings set it explicitly, so are unaffected — **selected**. +- **Default output.** + - Keep logs on stdout — pollutes `$(selenium-manager …)`. + - Follow standard CLI convention: result on stdout, diagnostics on stderr — **selected**. - **Unknown switch, or unknown value of a switch with a default.** - Error — turns expected skew into a broken session. - Warn and ignore the switch, or use the default value — **selected**.