From 92881551f1926a03033cb432f63f0467a7357ddd Mon Sep 17 00:00:00 2001 From: Titus Fortner Date: Wed, 10 Jun 2026 13:49:49 -0500 Subject: [PATCH] [docs] add design decision record process and template --- docs/decisions/0000-template.md | 56 ++++++++++++++++++++++++++ docs/decisions/README.md | 71 +++++++++++++++++++++++++++++++++ 2 files changed, 127 insertions(+) create mode 100644 docs/decisions/0000-template.md create mode 100644 docs/decisions/README.md diff --git a/docs/decisions/0000-template.md b/docs/decisions/0000-template.md new file mode 100644 index 0000000000000..a3377850d5517 --- /dev/null +++ b/docs/decisions/0000-template.md @@ -0,0 +1,56 @@ +# NNNN. Title stating the decision as a fact + + + +- Status: Proposed +- Date: YYYY-MM-DD +- Discussion: + +## Context + +What problem are we solving, and what forces are in tension? W3C spec language, user +expectations, existing behavior that differs between bindings, implementation constraints. +Link prior discussions (issues, TLC notes) here as background — but summarize them, since +this section must make sense without following any links. + +## Decision + +The decision, stated in language-neutral terms. This is the normative part: what every +binding MUST do, and what is explicitly left to per-language idiom. Use code sketches per +language here if the API shape is part of what's being decided. + +## Considered options + +- **Option A** — what it is; why it was rejected or accepted +- **Option B** — what it is; why it was rejected or accepted + + + +## Consequences + +What gets easier, what gets harder, what users will notice. Deprecations triggered by this +decision and their timelines. Follow-up decisions this one makes necessary. + +## Binding status + + + +| Binding | Status | Notes / tracking link | +|------------|---------|-----------------------| +| Java | pending | | +| Python | pending | | +| Ruby | pending | | +| .NET | pending | | +| JavaScript | pending | | + +## Appendix (optional) + +Durable supporting material the decision relies on: benchmarks, spec excerpts, survey of +behavior in other tools. Delete this section if there is none — ephemeral evidence belongs +in the PR thread instead. diff --git a/docs/decisions/README.md b/docs/decisions/README.md new file mode 100644 index 0000000000000..c706533c91fea --- /dev/null +++ b/docs/decisions/README.md @@ -0,0 +1,71 @@ +# 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`](https://github.com/SeleniumHQ/selenium/labels/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](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.