[docs] Selenium 5 release charter

[titusfortner]

📄 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

• ~2 years ago, at the TLC Summit in San Francisco, the plan
  (Selenium 5.0 milestone) was: implement
  the 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.
• Last year, at the TLC Summit in Valencia, the agreement was to implement every existing
  method with BiDi, each with a Classic fallback.
• December 2025 I consolidated to a minimal, focused release in
  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-over-BiDi migration.
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.

• BiDi support boundary — is BiDi internal-only, or is some surface supported, and where is the
  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.
• Network async/event API — the handler surface (add / remove / clear for requests, responses,
  and authentication; #13993) and how
  handlers behave (observe vs. intercept, disposition, ordering;
  #17685). [adr] Network async/event API proposal #17685 covers only the behavior; the
  agreed surface still needs to be folded into the same decision.
• Script and logging async/event API — the surface (pinned scripts; console, JS-error, and
  DOM-mutation handlers; #13992) and how it
  behaves. No ADR yet.
• Selenium Manager released API — formalize the interface and behaviors needed to drop the Beta
  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:

• Full classic-over-BiDi migration — routing classic commands through BiDi now, and the
  partial-BiDi support / Classic fallback that goes with it (navigation: #17715,
  #17232, POC #13190).
• DevTools deprecation — #13990.
• Convenience layers — expect_* event waiting (#17671),
  response body & request timing (#17674),
  navigation waiting (#17676).
• Browser context API — browsing contexts as handle objects
  (#17681).
• Capability mapping — exposing BiDi capability modules as high-level APIs: permissions
  (#17677), storage / cookies
  (#17673), emulation
  (#17675), user prompts
  (#17672).

[qodo-code-review]

PR Summary by Qodo

Document Selenium 5 release charter and formalize ADR tracking workflow
📝 Documentation ⚙️ Configuration changes 🕐 10-20 Minutes

Description

• Add a Selenium 5 release charter defining required ADRs and explicit out-of-scope items.
• Introduce ADR PR and issue templates to separate immutable decisions from implementation tracking.
• Update ADR docs/template to number records by PR and clarify scoping and content guidance.

Diagram

graph TD
A["ADR PR (template)"] --> B["ADR record file"] --> C["Accepted decision"] --> D["ADR tracking issue"]
E["Tracking issue template"] --> D
F["Selenium 5 charter"] --> B

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep per-binding status table inside ADR files

• ➕ All decision + rollout status visible in one place
• ➕ No reliance on GitHub issue tracking conventions
• ➖ Causes churn on otherwise-immutable ADR records as bindings converge
• ➖ Encourages post-acceptance edits to the committed decision artifact

2. Use a GitHub Project/board for convergence tracking

• ➕ Better cross-ADR and cross-binding rollup views
• ➕ Can automate status via PR links/workflows
• ➖ Harder to keep a single canonical link from each ADR PR
• ➖ More process/tooling overhead than a simple issue checklist

3. Track convergence via labels/milestones on implementing PRs

• ➕ Leverages existing GitHub primitives; minimal templates
• ➕ Queryable across repo
• ➖ Less structured per-binding checklist; easy to miss one binding
• ➖ Weaker narrative context for blockers/caveats than a dedicated tracking issue

Recommendation: The PR’s approach (immutable ADR records + separate post-acceptance tracking issues) is the best tradeoff: it preserves ADRs as durable design artifacts while still providing a lightweight, standardized convergence mechanism across bindings. A project board could be added later for rollups without changing the ADR/issue canonical linkage model.

Files changed (5) +203 / -33

Documentation (4) +160 / -33

adr.mdAdd ADR pull request template for proposal logistics +26/-0

Add ADR pull request template for proposal logistics

• Adds a PR template specifically for ADR proposals, instructing authors to keep the PR body focused on related links, proposal notes, discussion questions, and post-acceptance tracking. Reinforces that the decision content belongs in the ADR record file.

.github/PULL_REQUEST_TEMPLATE/adr.md

0000-template.mdRefine ADR record template: scope, behavior table, and immutability guidance +28/-22

Refine ADR record template: scope, behavior table, and immutability guidance

• Updates the ADR template to clarify that the ADR number is the PR number and that records should capture what/why rather than implementation details. Adds an optional current-behavior table for documenting cross-binding divergence, and removes the in-record binding status table in favor of a post-acceptance tracking issue.

docs/decisions/0000-template.md

README.mdDefine ADR scoping rules and move convergence tracking to issues +33/-11

Define ADR scoping rules and move convergence tracking to issues

• Clarifies that ADRs are numbered by their proposing PR number and adds guidance on when to bundle vs split related sub-decisions. Updates the process to use the ADR PR template query param and replaces in-record binding convergence tracking with a dedicated ADR tracking issue created from the new issue form.

docs/decisions/README.md

selenium-5.mdAdd Selenium 5 release charter document +73/-0

Add Selenium 5 release charter document

• Introduces a proposed Selenium 5 release charter that defines Selenium 5 as an alignment release and lists the ADR decisions required to ship (BiDi boundary, classic fallback, network and script/logging event APIs, Selenium Manager API). Explicitly marks several topics as out of scope for 5.0 (full classic-over-BiDi migration, DevTools deprecation, convenience layers, browser context API, capability mapping).

docs/plans/selenium-5.md

Other (1) +43 / -0

adr-tracking.ymlAdd ADR implementation tracking issue form +43/-0

Add ADR implementation tracking issue form

• Introduces a GitHub issue form to open standardized tracking issues once an ADR is accepted. Captures the accepted ADR link and provides a per-binding checklist (Java, Python, Ruby, .NET, JavaScript) plus notes for blockers/caveats.

.github/ISSUE_TEMPLATE/adr-tracking.yml

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📎 Requirement gaps (2) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. --selenium-version flag not required 📎 Requirement gap ≡ Correctness ⭐ New

Description

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.

Code

docs/plans/selenium-5.md[R38-41]

+### Selenium Manager released API — _ADR pending_
+
+Formalize the interface and behaviors required to drop the Beta label and release independently of
+the bindings.

Evidence

Rule 389279 requires Selenium Manager to require/use a --selenium-version flag rather than
inferring Selenium version from SM version, and rule 389280 requires all bindings to pass this flag.
The charter’s Selenium Manager section does not mention this flag or cross-binding passing
requirement.

Selenium Manager introduces a required --selenium-version flag for telemetry/version reporting
All bindings pass Selenium version to Selenium Manager via new --selenium-version flag
docs/plans/selenium-5.md[38-41]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

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

---

2. Selenium Manager versioning not specified ✗ Dismissed 📎 Requirement gap ≡ Correctness ⭐ New

Description

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.

Code

docs/plans/selenium-5.md[R38-41]

+### Selenium Manager released API — _ADR pending_
+
+Formalize the interface and behaviors required to drop the Beta label and release independently of
+the bindings.

Evidence

Rule 389278 requires Selenium Manager to adopt an independent version schema starting at
1.0.0-beta1 (or equivalent). The charter’s Selenium Manager section only says to formalize the
interface to drop the Beta label and release independently, but does not record the independent
versioning requirement.

Selenium Manager adopts independent version schema starting at 1.0.0-beta1
docs/plans/selenium-5.md[38-41]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

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

---

3. DevTools deprecation set out-of-scope ✗ Dismissed 📎 Requirement gap ≡ Correctness

Description

The charter explicitly lists DevTools (CDP) deprecation as out of scope for Selenium 5. This
conflicts with the compliance requirement that CDP APIs be deprecated in Selenium 5 with guidance
for BiDi feature requests.

Code

docs/plans/selenium-5.md[R57-60]

+### DevTools deprecation
+
+Deprecating or removing DevTools (CDP) support.
+

Evidence

PR Compliance ID 389279 requires CDP-related APIs to be deprecated in Selenium 5 with user guidance.
The new charter states "DevTools deprecation" is out of scope, which directly contradicts that
requirement.

CDP usage is deprecated in Selenium 5 with guidance for BiDi feature requests
docs/plans/selenium-5.md[57-60]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The Selenium 5 release charter marks DevTools (CDP) deprecation as out of scope, but the compliance checklist requires CDP usage to be deprecated in Selenium 5 and to include guidance for users on filing BiDi gap requests.

## Issue Context
This PR adds `docs/plans/selenium-5.md` as the release charter, so its in-scope/out-of-scope decisions must align with the Selenium 5 compliance requirements.

## Fix Focus Areas
- docs/plans/selenium-5.md[20-47]
- docs/plans/selenium-5.md[57-60]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View more (1)

4. Missing BiDi navigation requirement 📎 Requirement gap ≡ Correctness

Description

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.

Code

docs/plans/selenium-5.md[R20-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.
+

Evidence

PR Compliance ID 389276 requires BiDi navigation commands across bindings with
pageLoadStrategy-aware waiting. The new charter enumerates required items for release but does not
include navigation, indicating the charter scope is not aligned with the requirement.

BiDi Navigation commands implemented across bindings with pageLoadStrategy-aware waiting
docs/plans/selenium-5.md[20-47]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

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

---

5. Undefined ADR reference ✓ Resolved 🐞 Bug ⚙ Maintainability ⭐ New

Description

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.

Code

docs/plans/selenium-5.md[R53-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.

Evidence

The section defines “Full classic-over-BiDi migration” but later references a differently named ADR
(“Classic-migration ADR”), introducing an undefined name within the same area of the charter.

docs/plans/selenium-5.md[47-55]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

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

---

6. Ambiguous heading wording 🐞 Bug ⚙ Maintainability ⭐ New

Description

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.

Code

docs/plans/selenium-5.md[R38-41]

+### Selenium Manager released API — _ADR pending_
+
+Formalize the interface and behaviors required to drop the Beta label and release independently of
+the bindings.

Evidence

The heading uses “released API” while the description explicitly frames the work as dropping Beta
and enabling independent release, which can be read as not yet released.

docs/plans/selenium-5.md[38-41]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

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

---

Previous review results

Review updated until commit 6917144

Results up to commit de97f5f

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (1) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Missing BiDi navigation requirement 📎 Requirement gap ≡ Correctness

Description

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.

Code

docs/plans/selenium-5.md[R20-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.
+

Evidence

PR Compliance ID 389276 requires BiDi navigation commands across bindings with
pageLoadStrategy-aware waiting. The new charter enumerates required items for release but does not
include navigation, indicating the charter scope is not aligned with the requirement.

BiDi Navigation commands implemented across bindings with pageLoadStrategy-aware waiting
docs/plans/selenium-5.md[20-47]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

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

---

2. DevTools deprecation set out-of-scope ✗ Dismissed 📎 Requirement gap ≡ Correctness

Description

The charter explicitly lists DevTools (CDP) deprecation as out of scope for Selenium 5. This
conflicts with the compliance requirement that CDP APIs be deprecated in Selenium 5 with guidance
for BiDi feature requests.

Code

docs/plans/selenium-5.md[R57-60]

+### DevTools deprecation
+
+Deprecating or removing DevTools (CDP) support.
+

Evidence

PR Compliance ID 389279 requires CDP-related APIs to be deprecated in Selenium 5 with user guidance.
The new charter states "DevTools deprecation" is out of scope, which directly contradicts that
requirement.

CDP usage is deprecated in Selenium 5 with guidance for BiDi feature requests
docs/plans/selenium-5.md[57-60]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The Selenium 5 release charter marks DevTools (CDP) deprecation as out of scope, but the compliance checklist requires CDP usage to be deprecated in Selenium 5 and to include guidance for users on filing BiDi gap requests.

## Issue Context
This PR adds `docs/plans/selenium-5.md` as the release charter, so its in-scope/out-of-scope decisions must align with the Selenium 5 compliance requirements.

## Fix Focus Areas
- docs/plans/selenium-5.md[20-47]
- docs/plans/selenium-5.md[57-60]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[qodo-code-review]

Code review by qodo was updated up to the latest commit de97f5f

[diemol]

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.

[qodo-code-review]

Code review by qodo was updated up to the latest commit 5886f13

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Status line uses HTML comment ✓ Resolved 📘 Rule violation ⚙ Maintainability

Description

The new charter includes HTML comments that mainly restate allowed values/placeholder instructions
rather than capturing rationale, which reduces maintainability. Prefer making this guidance explicit
prose (or explaining why these fields exist) instead of hidden comments.

Code

docs/plans/selenium-5.md[R3-5]

+- Status: Proposed <!-- Proposed | Accepted | Released | Superseded -->
+- Owner: Selenium Technical Leadership Committee (TLC)
+- Discussion: <!-- link to this charter's PR -->

Evidence

PR Compliance ID 7 requires comments to focus on rationale/intent rather than restating mechanics.
The added lines include <!-- Proposed | Accepted | Released | Superseded --> and `<!-- link to
this charter's PR -->`, which are placeholder/"what to fill" comments rather than "why"
explanations.

AGENTS.md: Comments Should Explain Why, Not What
docs/plans/selenium-5.md[3-5]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/plans/selenium-5.md` uses HTML comments for status/options and a PR link placeholder. These comments communicate "what" to fill in, but do not explain rationale and are easy to miss.

## Issue Context
Compliance prefers comments/documentation to explain intent/rationale rather than restating obvious mechanics or hiding required fields in HTML comments.

## Fix Focus Areas
- docs/plans/selenium-5.md[3-5]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[qodo-code-review]

Code review by qodo was updated up to the latest commit 6917144