Design Decisions

This directory is the log of design decisions that apply across the Selenium project — one file per decision, numbered in the order they were proposed.

Selenium ships the same API in multiple languages. Decisions about user-visible behavior, API shape, and cross-binding semantics need to be made once, recorded, and implemented consistently everywhere. This log is the canonical record of those decisions: when a question comes up in review, the answer should be a link to a file here.

What needs a decision record

• User-visible behavior that should be consistent across bindings: API naming and shape, error types and messages, default timeouts, capability handling
• WebDriver Classic / BiDi semantics and how the protocol is exposed (or deliberately not exposed)
• Deprecation and backwards-compatibility commitments
• Anything the TLC has labeled A-needs-decision and resolved

What doesn't

• Single-binding internals (a Java maintainer picking a data structure)
• Build tooling and infrastructure choices
• Anything cheaply reversible

When in doubt, ask whether the question is likely to be raised again. If it is, record the decision.

Process

1. Propose. Anyone may propose: copy 0000-template.md to NNNN-short-title.md using the next unused number, fill it in, and open a PR with Status: Proposed. Keep it to about a page — if the debate already happened in an issue, the record can be short and link to it.
2. Discuss. The PR thread is the discussion record. Decisions that need synchronous discussion are raised at a TLC meeting; the outcome goes back into the PR. Disagreement about the considered options is resolved by revising the document during review, so the merged record reflects the debate accurately. The TLC sets its meeting agenda; proposals advance as agenda time allows.
3. Decide. The Selenium Project Lead merges the record once the approval requirements below are met and discussion has run its course, with the status updated to Accepted — merging constitutes acceptance. Proposals the TLC considers and declines are merged as Rejected; proposals withdrawn or abandoned before TLC consideration are closed and the number lapses.
4. Implement. Each binding tracks its convergence in the decision‘s binding-status table. Updating that table (and only that table) doesn’t require TLC review.

Approval

• TLC members respond to a proposal with a GitHub review: an approval, a “no objection” comment review (saw it, deferring to the others), or a request-changes review stating what would resolve it.
• Records are accepted by consensus: a majority of TLC members have responded, none with an unresolved objection. Before acceptance, a record must have been open at least one week and an agenda item at a TLC meeting — no one should learn of a decision after it is made.
• If substantive edits are made, the author re-requests reviews.
• An objection that revision cannot resolve — including support for a different considered option — is discussed at a TLC meeting. If consensus still fails, the Selenium Project Lead decides which position prevails; the record is updated to match, and overruled dissent is summarized rather than erased.

Rules

• A decision must stand alone. A reader gets the decision, the rationale, and the rejected alternatives without following any links; linked material is background, not required reading.
• Accepted decisions are immutable, except for the status line and the binding-status table. Changing a decision means a new record that supersedes the old one — update the old record's status to Superseded by [NNNN](...).
• Numbers are stable once merged. They get cited in reviews and issues. If two open PRs claim the same number, the later one renames before merge. Gaps in numbering are acceptable.
• Durable supporting material goes in the record itself (an Appendix section at the end). Ephemeral evidence and debate stay in the PR thread.