From 68cbfff407d12cdc9835f25bfb5851f742c77bc3 Mon Sep 17 00:00:00 2001 From: Titus Fortner Date: Sat, 20 Jun 2026 18:59:05 -0500 Subject: [PATCH 01/10] [docs] number ADRs by PR and track binding convergence in an issue --- .github/ISSUE_TEMPLATE/adr-tracking.yml | 43 +++++++++++++++++++++++++ docs/decisions/0000-template.md | 21 ++++-------- docs/decisions/README.md | 25 +++++++------- 3 files changed, 63 insertions(+), 26 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/adr-tracking.yml diff --git a/.github/ISSUE_TEMPLATE/adr-tracking.yml b/.github/ISSUE_TEMPLATE/adr-tracking.yml new file mode 100644 index 0000000000000..607775279e5b8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/adr-tracking.yml @@ -0,0 +1,43 @@ +name: 📋 ADR Implementation Tracking +description: Track per-binding convergence on an accepted design decision record (ADR) +title: "[📋 ADR]: " +body: + - type: markdown + attributes: + value: | + Open this issue when a design decision record is **Accepted**. It tracks each binding's + progress toward implementing the decision so the committed record stays immutable. + Link it from the record's PR. See [docs/decisions/README.md](https://github.com/SeleniumHQ/selenium/blob/trunk/docs/decisions/README.md). + + - type: input + id: record + attributes: + label: Decision record + description: Link to the accepted record and its PR (the record number is the PR number). + placeholder: "docs/decisions/NNNN-title.md (#NNNN)" + validations: + required: true + + - type: textarea + id: bindings + attributes: + label: Binding implementation + description: | + Replace each placeholder with the implementing PR and check the box when it merges. + Mark a binding `n/a` with a note if the decision does not apply to it. + value: | + - [ ] Java — _PR_ + - [ ] Python — _PR_ + - [ ] Ruby — _PR_ + - [ ] .NET — _PR_ + - [ ] JavaScript — _PR_ + validations: + required: true + + - type: textarea + id: notes + attributes: + label: Notes + description: Anything blocking convergence, or per-binding caveats discovered during implementation. + validations: + required: false diff --git a/docs/decisions/0000-template.md b/docs/decisions/0000-template.md index a3377850d5517..825e5d9b98fca 100644 --- a/docs/decisions/0000-template.md +++ b/docs/decisions/0000-template.md @@ -1,10 +1,9 @@ # NNNN. Title stating the decision as a fact - + - Status: Proposed -- Date: YYYY-MM-DD - Discussion: ## Context @@ -36,18 +35,10 @@ language here if the API shape is part of what's being decided. 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) diff --git a/docs/decisions/README.md b/docs/decisions/README.md index c706533c91fea..f8b363d0dc93a 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -1,7 +1,7 @@ # 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. +one file per decision, numbered by the pull request that proposes it. 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 @@ -27,9 +27,10 @@ When in doubt, ask whether the question is likely to be raised again. If it is, ## 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. +1. **Propose.** Anyone may propose: copy [0000-template.md](0000-template.md) to `short-title.md`, + fill it in with `Status: Proposed`, and open a PR. Once GitHub assigns the PR number, rename the + file to `NNNN-short-title.md` using that number, before merge. 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 @@ -40,8 +41,11 @@ When in doubt, ask whether the question is likely to be raised again. If it is, 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. +4. **Implement.** When a record is accepted, open an ADR tracking issue (use the + [ADR Implementation Tracking](../../.github/ISSUE_TEMPLATE/adr-tracking.yml) issue template) — one + checkbox per binding, linking each implementing PR as it lands — and link the issue from the + record's PR. Tracking lives in the issue, not the committed record, so the immutable file doesn't + churn as bindings converge; updating the issue needs no TLC review. ## Approval @@ -62,10 +66,9 @@ When in doubt, ask whether the question is likely to be raised again. If it is, - **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. +- **Accepted decisions are immutable**, except for the status line. Changing a decision means a + new record that supersedes the old one — update the old record's status to `Superseded by [NNNN](...)`. +- **The number is the proposal's PR number.** It gets cited in reviews and issues and links + straight to the discussion. Gaps in numbering are expected. - **Durable supporting material goes in the record itself** (an Appendix section at the end). Ephemeral evidence and debate stay in the PR thread. From 8e7cae9eb881301f5b92a31eb6ca74ead2694705 Mon Sep 17 00:00:00 2001 From: Titus Fortner Date: Sun, 21 Jun 2026 07:35:31 -0500 Subject: [PATCH 02/10] [docs] link ADR tracking to the new-issue form, not the template source --- docs/decisions/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/decisions/README.md b/docs/decisions/README.md index f8b363d0dc93a..3378d1a6c2b6e 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -42,7 +42,7 @@ When in doubt, ask whether the question is likely to be raised again. If it is, `Rejected`; proposals withdrawn or abandoned before TLC consideration are closed and the number lapses. 4. **Implement.** When a record is accepted, open an ADR tracking issue (use the - [ADR Implementation Tracking](../../.github/ISSUE_TEMPLATE/adr-tracking.yml) issue template) — one + [ADR Implementation Tracking](https://github.com/SeleniumHQ/selenium/issues/new?template=adr-tracking.yml) issue template) — one checkbox per binding, linking each implementing PR as it lands — and link the issue from the record's PR. Tracking lives in the issue, not the committed record, so the immutable file doesn't churn as bindings converge; updating the issue needs no TLC review. From 1f202c30f255dd24846de1a6f70f16fb2549ed16 Mon Sep 17 00:00:00 2001 From: Titus Fortner Date: Sun, 21 Jun 2026 13:03:39 -0500 Subject: [PATCH 03/10] [docs] clarify ADR scope: group related choices, keep records out of implementation --- docs/decisions/0000-template.md | 16 +++++++++------- docs/decisions/README.md | 14 ++++++++++++++ 2 files changed, 23 insertions(+), 7 deletions(-) diff --git a/docs/decisions/0000-template.md b/docs/decisions/0000-template.md index 825e5d9b98fca..74c149cca17a6 100644 --- a/docs/decisions/0000-template.md +++ b/docs/decisions/0000-template.md @@ -16,19 +16,21 @@ 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. +binding MUST do, and what is explicitly left to per-language idiom. Record *what* and *why*, +not *how* — implementation lives in the adopting PRs. Use code sketches only to pin down the +API shape being decided, not to specify implementation. ## 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 diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 3378d1a6c2b6e..009fcd1c8fc43 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -25,6 +25,18 @@ question comes up in review, the answer should be a link to a file here. When in doubt, ask whether the question is likely to be raised again. If it is, record the decision. +## Scope: what belongs in one record + +A record captures one coherent decision — which usually means a cluster of related sub-choices +that share the same context and rationale and are settled as a unit. Bundling those is correct, +not a flaw: a record on how clicks behave can settle scrolling, hit-testing, and pointer movement +together because they are one design with one rationale. + +The test for splitting is **not** "could this part be adopted on its own?" — almost any part can. +Split only when a sub-choice has its own rationale that stands without the others, would be debated +and decided separately, or could later be reversed without disturbing the rest. If splitting would +force a reader to open several records to understand any one of them, they belong in the same record. + ## Process 1. **Propose.** Anyone may propose: copy [0000-template.md](0000-template.md) to `short-title.md`, @@ -66,6 +78,8 @@ When in doubt, ask whether the question is likely to be raised again. If it is, - **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. +- **A record fixes the decision and its rationale, not the implementation.** It says what every + binding must do and why; how each binding builds it lives in the adopting PRs and code. - **Accepted decisions are immutable**, except for the status line. Changing a decision means a new record that supersedes the old one — update the old record's status to `Superseded by [NNNN](...)`. - **The number is the proposal's PR number.** It gets cited in reviews and issues and links From 765981fdc35c2ab2dfea828177f1f21c9556658d Mon Sep 17 00:00:00 2001 From: Titus Fortner Date: Sun, 21 Jun 2026 14:30:29 -0500 Subject: [PATCH 04/10] [docs] add ADR pull-request template and document its use --- .github/PULL_REQUEST_TEMPLATE/adr.md | 23 +++++++++++++++++++++++ docs/decisions/README.md | 5 +++++ 2 files changed, 28 insertions(+) create mode 100644 .github/PULL_REQUEST_TEMPLATE/adr.md diff --git a/.github/PULL_REQUEST_TEMPLATE/adr.md b/.github/PULL_REQUEST_TEMPLATE/adr.md new file mode 100644 index 0000000000000..07a23f4378c64 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/adr.md @@ -0,0 +1,23 @@ + + +### 📋 Proposed record + +Proposes ADR: **_short title_** + +- Record: `docs/decisions/NNNN-short-title.md` + +The decision, rationale, considered options, and consequences live in the record file. This PR +body is only for review logistics — don't restate the decision here. + +### 🗣 For reviewers + +What needs discussion or sign-off before this can be accepted? Link any prior issues or threads. + +### 🤖 AI assistance + +- [ ] No substantial AI assistance used +- [ ] AI assisted (complete below) + - Tool(s): + - What was generated: + - [ ] I reviewed all AI output and can explain the change diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 009fcd1c8fc43..2c68f42d3f61a 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -43,6 +43,11 @@ force a reader to open several records to understand any one of them, they belon fill it in with `Status: Proposed`, and open a PR. Once GitHub assigns the PR number, rename the file to `NNNN-short-title.md` using that number, before merge. Keep it to about a page — if the debate already happened in an issue, the record can be short and link to it. + + Open the PR with the ADR pull-request template by appending `?expand=1&template=adr.md` to the + compare URL — GitHub has no picker for PR templates, so this query parameter is the only way to + select it (e.g. `https://github.com/SeleniumHQ/selenium/compare/trunk...your-branch?expand=1&template=adr.md`). + Keep the PR body to review logistics; the decision and rationale belong in the record, not the PR. 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 From 533e2fbcc9bc56066829c70342b90a2bf897bfaf Mon Sep 17 00:00:00 2001 From: Titus Fortner Date: Sun, 21 Jun 2026 14:30:34 -0500 Subject: [PATCH 05/10] [docs] add optional current-behavior table to ADR Context --- docs/decisions/0000-template.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/decisions/0000-template.md b/docs/decisions/0000-template.md index 74c149cca17a6..be0d8def44387 100644 --- a/docs/decisions/0000-template.md +++ b/docs/decisions/0000-template.md @@ -13,6 +13,19 @@ expectations, existing behavior that differs between bindings, implementation co Link prior discussions (issues, TLC notes) here as background — but summarize them, since this section must make sense without following any links. + + +| Binding | Current behavior | +|------------|------------------| +| Java | | +| Python | | +| Ruby | | +| .NET | | +| JavaScript | | + ## Decision The decision, stated in language-neutral terms. This is the normative part: what every From 18c53ab69142e94438098f1de1a1eb1ce5b3a59e Mon Sep 17 00:00:00 2001 From: Titus Fortner Date: Sun, 21 Jun 2026 14:46:17 -0500 Subject: [PATCH 06/10] [docs] drop AI-assistance section from ADR PR template --- .github/PULL_REQUEST_TEMPLATE/adr.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE/adr.md b/.github/PULL_REQUEST_TEMPLATE/adr.md index 07a23f4378c64..db12376a6b82f 100644 --- a/.github/PULL_REQUEST_TEMPLATE/adr.md +++ b/.github/PULL_REQUEST_TEMPLATE/adr.md @@ -13,11 +13,3 @@ body is only for review logistics — don't restate the decision here. ### 🗣 For reviewers What needs discussion or sign-off before this can be accepted? Link any prior issues or threads. - -### 🤖 AI assistance - -- [ ] No substantial AI assistance used -- [ ] AI assisted (complete below) - - Tool(s): - - What was generated: - - [ ] I reviewed all AI output and can explain the change From 3754bd8eef3dc9d595498ebcbfe2350e9cb994fb Mon Sep 17 00:00:00 2001 From: Titus Fortner Date: Sun, 21 Jun 2026 15:51:50 -0500 Subject: [PATCH 07/10] [docs] ground ADR PR template in real usage: related links and TLC discussion --- .github/PULL_REQUEST_TEMPLATE/adr.md | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE/adr.md b/.github/PULL_REQUEST_TEMPLATE/adr.md index db12376a6b82f..50f26975aa3a7 100644 --- a/.github/PULL_REQUEST_TEMPLATE/adr.md +++ b/.github/PULL_REQUEST_TEMPLATE/adr.md @@ -1,15 +1,20 @@ - + -### 📋 Proposed record +The decision, rationale, considered options, and consequences are in the record file this PR +adds — don't restate them here. This body is only for review logistics. -Proposes ADR: **_short title_** +### 🔗 Related -- Record: `docs/decisions/NNNN-short-title.md` + -The decision, rationale, considered options, and consequences live in the record file. This PR -body is only for review logistics — don't restate the decision here. +### 🗣 TLC discussion -### 🗣 For reviewers + -What needs discussion or sign-off before this can be accepted? Link any prior issues or threads. +### 📌 Tracking + + +Tracking issue: _(linked on acceptance)_ From e73163a560e71b648e6077fefad6ae6cea4e5bde Mon Sep 17 00:00:00 2001 From: Titus Fortner Date: Sun, 21 Jun 2026 16:21:12 -0500 Subject: [PATCH 08/10] [docs] move ADR PR template guidance into a comment --- .github/PULL_REQUEST_TEMPLATE/adr.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE/adr.md b/.github/PULL_REQUEST_TEMPLATE/adr.md index 50f26975aa3a7..822f800af105b 100644 --- a/.github/PULL_REQUEST_TEMPLATE/adr.md +++ b/.github/PULL_REQUEST_TEMPLATE/adr.md @@ -1,9 +1,8 @@ -The decision, rationale, considered options, and consequences are in the record file this PR -adds — don't restate them here. This body is only for review logistics. - ### 🔗 Related + + +📄 The decision, its rationale, considered options, and consequences are in the record file +this PR adds; read it there. The sections below are proposal notes and review logistics. + +### 📝 Proposal notes + + ### 🔗 Related From 532550cf6426ce8ebd485fa4db722247e8286380 Mon Sep 17 00:00:00 2001 From: Titus Fortner Date: Sun, 21 Jun 2026 17:16:30 -0500 Subject: [PATCH 10/10] [docs] reorder ADR PR template; frame contention as discussion questions --- .github/PULL_REQUEST_TEMPLATE/adr.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE/adr.md b/.github/PULL_REQUEST_TEMPLATE/adr.md index 2cdd47ec68490..20c1cd3f00165 100644 --- a/.github/PULL_REQUEST_TEMPLATE/adr.md +++ b/.github/PULL_REQUEST_TEMPLATE/adr.md @@ -5,21 +5,20 @@ 📄 The decision, its rationale, considered options, and consequences are in the record file this PR adds; read it there. The sections below are proposal notes and review logistics. -### 📝 Proposal notes - - - ### 🔗 Related -### 🗣 TLC discussion +### 📝 Proposal notes + + + +### 🗣 Discussion - + ### 📌 Tracking