[docs] Selenium 5 release charter#17717
Open
titusfortner wants to merge 3 commits into
Open
Conversation
Contributor
PR Summary by QodoDocument Selenium 5 release charter and formalize ADR tracking workflow Description
Diagram
High-Level Assessment
Files changed (5)
|
Contributor
Code Review by Qodo
Context used✅ Tickets:
🎫 [🚀 Feature]: Implement Navigation Commands with BiDi 🎫 [🚀 Feature]: Change version format in Selenium Manager 🎫 [🚀 Feature]: Implement high level BiDi script commands +2 more✅ Compliance rules (platform):
11 rules 1. Selenium Manager versioning not specified
|
titusfortner
force-pushed
the
c/modest-benz-4f2db6
branch
from
f5acd6e to
de97f5f
Compare
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
Comment on lines
+20
to
+47
| ## Required for release | ||
|
|
||
| ### BiDi support boundary — _ADR pending_ | ||
|
|
||
| How the WebDriver BiDi protocol is exposed to users across the bindings. The ADR sets where the | ||
| boundary sits between supported Selenium API and internal implementation, and how each binding | ||
| marks it. | ||
|
|
||
| ### Classic fallback for BiDi-backed commands — _ADR pending_ | ||
|
|
||
| A defined, cross-binding mechanism for running a supported command over BiDi and falling back to | ||
| Classic when BiDi or the browser does not support it. The mechanism is required; migrating every | ||
| command is not. | ||
|
|
||
| ### Network async/event API — _ADR pending_ | ||
|
|
||
| The cross-binding API for adding, removing, and clearing handlers for requests, responses, and | ||
| authentication. | ||
|
|
||
| ### Script and logging async/event API — _ADR pending_ | ||
|
|
||
| The cross-binding API for pinned scripts (pin / unpin / execute) and for console-message, | ||
| JavaScript-error, and DOM-mutation handlers. | ||
|
|
||
| ### Selenium Manager finalized API — _ADR pending_ | ||
|
|
||
| A finalized, documented API the bindings invoke, versioned independently of the client. | ||
|
|
Contributor
There was a problem hiding this comment.
2. Missing bidi navigation requirement 📎 Requirement gap ≡ Correctness
The charter's "Required for release" list omits BiDi navigation commands and pageLoadStrategy-aware waiting. This fails to reflect the compliance requirement that BiDi-based navigation be implemented across bindings with page load strategy respected.
Agent Prompt
## Issue description
The Selenium 5 release charter does not list BiDi-based navigation (with pageLoadStrategy-aware waiting) as a required-for-release item, even though the compliance checklist mandates it as a minimum viable BiDi module across bindings.
## Issue Context
This document is positioned as the definitive list of decisions/features required for Selenium 5. If navigation is required for release, it should be explicitly listed and tied to the ADR/design work.
## Fix Focus Areas
- docs/plans/selenium-5.md[20-47]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Member
Author
There was a problem hiding this comment.
The intent was to make this part of the ADR for "Classic fallback for BiDi-backed commands" since it is kind of an implementation detail. But agreed, especially if we are going to move that bullet to out of scope (not a requirement for Selenium 5) we need to decide separately if we want to define the mechanism for deciding BiDi vs Classic path for sessions and implement something like Navigation, which Ruby already does.
Contributor
|
Code review by qodo was updated up to the latest commit de97f5f |
AutomatedTester
approved these changes
Jun 25, 2026
titusfortner
commented
Jun 25, 2026
| boundary sits between supported Selenium API and internal implementation, and how each binding | ||
| marks it. | ||
|
|
||
| ### Classic fallback for BiDi-backed commands — _ADR pending_ |
Member
Author
There was a problem hiding this comment.
- This is too specific of subject. It should be "Partial BiDi implementation support" where we decide what it means to support a remote end that doesn't implement every feature.
- One specific issue with the "per command" fallback is that not all commands can switch between classic and bidi depending on what previous commands were sent
- This issue is not just about "what if Safaridriver implements BiDi support but not for everything at first" it can also be about supporting older browsers with inicomplete BiDi implementations
The consensus at the 6/25 TLC meeting was that this probably doesn't belong as a blocker or a prerequisite for Selenium 5, and it can be part of the ADR for the Classic Migration.
Member
There was a problem hiding this comment.
We're taking that out per 7/2 TLC meeting.
diemol
reviewed
Jun 25, 2026
| boundary sits between supported Selenium API and internal implementation, and how each binding | ||
| marks it. | ||
|
|
||
| ### Classic fallback for BiDi-backed commands — _ADR pending_ |
Member
There was a problem hiding this comment.
This could be an implementation detail of the migration to Selenium 5 ADR.
p0deje
approved these changes
Jul 2, 2026
| boundary sits between supported Selenium API and internal implementation, and how each binding | ||
| marks it. | ||
|
|
||
| ### Classic fallback for BiDi-backed commands — _ADR pending_ |
Member
There was a problem hiding this comment.
We're taking that out per 7/2 TLC meeting.
diemol
reviewed
Jul 2, 2026
diemol
left a comment
diemol
left a comment
Member
There was a problem hiding this comment.
In the TLC meeting (2.7.2026) it was decided that Titus will address the comments, then we will review and approve to merge this.
pujagani
approved these changes
Jul 2, 2026
Comment on lines
+38
to
+41
| ### Selenium Manager released API — _ADR pending_ | ||
|
|
||
| Formalize the interface and behaviors required to drop the Beta label and release independently of | ||
| the bindings. |
Contributor
There was a problem hiding this comment.
1. Selenium manager versioning not specified 📎 Requirement gap ≡ Correctness
The new Selenium Manager released API required item does not state the required independent Selenium Manager version schema (e.g., starting at 1.0.0-beta1). Without explicitly capturing this requirement in the charter, the Selenium 5 scope can ship without meeting the versioning compliance objective.
Agent Prompt
## Issue description
The Selenium 5 charter section `Selenium Manager released API — ADR pending` does not mention the required independent Selenium Manager version schema (e.g., `1.0.0-beta1`), which is a compliance requirement for Selenium 5.
## Issue Context
The charter is the index of decisions required for Selenium 5; the Selenium Manager decision should explicitly include the independent versioning requirement so the ADR cannot omit it.
## Fix Focus Areas
- docs/plans/selenium-5.md[38-41]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
+38
to
+41
| ### Selenium Manager released API — _ADR pending_ | ||
|
|
||
| Formalize the interface and behaviors required to drop the Beta label and release independently of | ||
| the bindings. |
Contributor
There was a problem hiding this comment.
2. --selenium-version flag not required 📎 Requirement gap ≡ Correctness
The new Selenium Manager released API required item does not specify introducing/using a required --selenium-version flag for telemetry/version reporting, nor that all bindings must pass it. This risks keeping the existing inferred mapping behavior and inconsistent cross-binding adoption.
Agent Prompt
## Issue description
The Selenium 5 charter does not record the Selenium Manager requirement to use an explicit `--selenium-version` flag for telemetry/version reporting, nor the requirement that all bindings pass it.
## Issue Context
These are Selenium 5 compliance requirements and should be explicitly captured under the `Selenium Manager released API` ADR scope so the resulting ADR and implementations across bindings cannot omit them.
## Fix Focus Areas
- docs/plans/selenium-5.md[38-41]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
+53
to
+55
| What it means to support a remote end that does not implement every BiDi feature — choosing the | ||
| BiDi or Classic path per session (not every command can switch mid-session), for older browsers or | ||
| drivers with incomplete BiDi. Part of the Classic-migration ADR. |
Contributor
There was a problem hiding this comment.
3. Undefined adr reference 🐞 Bug ⚙ Maintainability
The “Partial BiDi implementation support” section says it is “Part of the Classic-migration ADR,” but this charter uses “classic-over-BiDi migration” terminology and the phrase “Classic-migration ADR” appears nowhere else, making the intended cross-reference unclear.
Agent Prompt
## Issue description
The charter references a "Classic-migration ADR" that is not defined elsewhere in the document and does not match the surrounding terminology ("classic-over-BiDi migration"), reducing searchability and making future linking ambiguous.
## Issue Context
This is in the Out of scope section under "Partial BiDi implementation support".
## Fix Focus Areas
- docs/plans/selenium-5.md[47-55]
## Suggested fix
Replace “Classic-migration ADR” with terminology that matches the charter section title (e.g., “classic-over-BiDi migration ADR”), and optionally make it an explicit intra-doc link to the “Full classic-over-BiDi migration” section.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
+38
to
+41
| ### Selenium Manager released API — _ADR pending_ | ||
|
|
||
| Formalize the interface and behaviors required to drop the Beta label and release independently of | ||
| the bindings. |
Contributor
There was a problem hiding this comment.
4. Ambiguous heading wording 🐞 Bug ⚙ Maintainability
The heading “Selenium Manager released API” is paired with body text describing work needed to “drop the Beta label,” which mixes present/future state and can mislead readers about whether this is already released vs. a release goal.
Agent Prompt
## Issue description
The section title reads as if the API is already released (“released API”), while the description says the purpose is to drop the Beta label and release independently, which reads like future work. This is a clarity/terminology mismatch.
## Issue Context
This is in the Required for release list under Selenium Manager.
## Fix Focus Areas
- docs/plans/selenium-5.md[38-41]
## Suggested fix
Rename the heading to reflect intent (e.g., “Selenium Manager release/GA API” or “Selenium Manager finalized API”), or adjust the body text to clearly indicate this is the target for 5.0 rather than current state.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Contributor
|
Code review by qodo was updated up to the latest commit 5886f13 |
gsnedders
reviewed
Jul 8, 2026
Comment on lines
+51
to
+55
| ### Partial BiDi implementation support | ||
|
|
||
| What it means to support a remote end that does not implement every BiDi feature — choosing the | ||
| BiDi or Classic path per session (not every command can switch mid-session), for older browsers or | ||
| drivers with incomplete BiDi. Part of the Classic-migration ADR. |
There was a problem hiding this comment.
Given there continue to be additions to BiDi, e.g., w3c/webdriver-bidi@54175aaf, it's probably worthwhile defining what counts as partial/incomplete support, because otherwise both Chrome and Firefox are out-of-scope. Even going back to spec changes around a year ago, you'll run into Firefox not supporting the emulation.setScriptingEnabled command, in case that makes it out-of-scope.
That said, I think it should be obvious that support of browsingContext.StartScreencast and emulation.setScriptingEnabled are not really comparable to support of browsingContext.create.
More interestingly would be cases like supporting everything except the emulation module, or supporting only the commands that correspond to Classic ones. Are those out-of-scope?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
7 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
📄 The agreed scope is in
docs/plans/selenium-5.md— read it there. This body is the context:why we need it, the required decisions, and the possible additions to consider.
Why we need this
We have dozens of ADR PRs in flight, and many assume different answers to "what is Selenium 5."
Binding-level efforts in .NET and Python are each moving on their own reading of the goal. We need
one agreed boundary for what blocks the release before arguing implementation details. This
charter is that boundary; the cross-binding mechanics are left to the ADRs it lists.
How the scope has moved
(
Selenium 5.0milestone) was: implementthe BiDi API, take Selenium Manager out of beta, deprecate CDP, with big breaking changes — and a
Classic fallback so enabling BiDi never changed existing behavior.
method with BiDi, each with a Classic fallback.
seleniumhq.github.io#2556.
This charter takes the #2556 scope. The Classic-fallback mechanism, in the plan since the start,
was removed from 5.0 scope at the 6/25 TLC meeting and folded into the Classic-migration ADR. Where
an older milestone or issue conflicts with the charter, the charter governs 5.0 scope.
Required decisions
Each must be settled by an accepted ADR before 5.0 ships; none is accepted yet. Each ADR has to
consolidate both what we agreed to implement — the surface, much of it settled at the summits
before we used ADRs — and how it behaves. The existing PRs cover only parts of that.
line? #17670 proposes internal-only.
#17709 describes three layers but does not
say which is supported, why, or how they differ — so it does not yet define the boundary. The ADR
has to pin where supported ends and internal begins, and on what basis.
and authentication; #13993) and how
handlers behave (observe vs. intercept, disposition, ordering;
#17685). [adr] network handler behavior proposal #17685 covers only the behavior; the
agreed surface still needs to be folded into the same decision.
DOM-mutation handlers; #13992) and how it
behaves. No ADR yet.
label and release independently of the bindings (e.g. how an unrecognized command is handled).
Proposed in #17741; issues
#11694,
#15754,
#17554.
Possible additions to consider
Subjects the charter defers; this PR is where we decide whether any should be required for 5.0. The
charter decides only whether a subject is in scope — each linked ADR is the design proposal
if it is. Each has an in-flight proposal:
partial-BiDi support / Classic fallback that goes with it (navigation: #17715,
#17232, POC #13190).
expect_*event waiting (#17671),response body & request timing (#17674),
navigation waiting (#17676).
(#17681).
(#17677), storage / cookies
(#17673), emulation
(#17675), user prompts
(#17672).