[docs] add design decision record process and template

[titusfortner]

💥 What does this PR do?

Adds docs/decisions/ — a lightweight process for recording design decisions that apply across bindings (API shape, cross-binding semantics, deprecation commitments), plus the template for writing one. Decisions are proposed as PRs, discussed on the PR thread and at TLC meetings, and accepted by TLC consensus; the merged file is the canonical record, so settled questions get answered with a link instead of being re-litigated.

🔧 Implementation Notes

• Format is based on MADR/Nygard ADRs with one Selenium-specific addition: a per-binding status table so convergence across the five bindings is tracked in the record itself.
• These live in trunk rather than the website repo because the audience is contributors and the merge-is-acceptance process depends on the code-review flow. They can be rendered to selenium.dev later without moving the source of truth.

🤖 AI assistance

• AI assisted (complete below)
  • Tool(s): Claude Code
  • What was generated: Initial drafts of the README and template, revised through discussion and review
  • I reviewed all AI output and can explain the change

💡 Additional Considerations

• This PR follows the process it introduces: feedback is encouraged from all contributors; it merges by TLC consensus — a majority of TLC members responding with no unresolved objections, after at least one week open and discussion at a TLC meeting — with the Selenium Project Lead performing the merge. Merging adopts the process.

🔄 Types of changes

• Documentation (contributor process)

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1)📘 Rule violations (0)

1. Filename convention mismatch 🐞 Bug⚙ Maintainability

Description

The ADR template’s supersedence example points to NNNN-title.md, but the README standardizes
decision filenames as NNNN-short-title.md, creating conflicting guidance that can lead to
inconsistent ADR filenames/links when contributors copy the template verbatim.

Code

docs/decisions/0000-template.md[6]

+- Status: Proposed <!-- Proposed | Accepted | Rejected | Superseded by [NNNN](NNNN-title.md) -->

Evidence

The README defines the canonical ADR filename format as NNNN-short-title.md, while the template’s
status-line example uses a different filename (NNNN-title.md), so the two new docs conflict on how
supersedence links should be written.

docs/decisions/README.md[30-32]
docs/decisions/0000-template.md[6-6]
docs/decisions/README.md[65-67]

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 ADR template and README disagree on the expected decision filename pattern for supersedence links (`NNNN-title.md` vs `NNNN-short-title.md`). This can cause inconsistent file naming and incorrect/inconsistent links across ADRs.
## Issue Context
- README instructs authors to create ADRs as `NNNN-short-title.md`.
- Template’s status-line comment suggests `Superseded by [NNNN](NNNN-title.md)`.
## Fix Focus Areas
- docs/decisions/0000-template.md[6-6]
- docs/decisions/README.md[30-32]
- docs/decisions/README.md[65-67]
## Suggested fix
- Update the template’s supersedence example to use `NNNN-short-title.md` (or a neutral placeholder matching the README’s convention).
- Update the README’s `Superseded by [NNNN](...)` example to show the same filename pattern explicitly (e.g., `Superseded by [NNNN](NNNN-short-title.md)`).

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

---

Previous review results

Review updated until commit 9288155

Results up to commit 9554f29

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

1. Filename convention mismatch 🐞 Bug⚙ Maintainability

Description

The ADR template’s supersedence example points to NNNN-title.md, but the README standardizes
decision filenames as NNNN-short-title.md, creating conflicting guidance that can lead to
inconsistent ADR filenames/links when contributors copy the template verbatim.

Code

docs/decisions/0000-template.md[6]

+- Status: Proposed <!-- Proposed | Accepted | Rejected | Superseded by [NNNN](NNNN-title.md) -->

Evidence

The README defines the canonical ADR filename format as NNNN-short-title.md, while the template’s
status-line example uses a different filename (NNNN-title.md), so the two new docs conflict on how
supersedence links should be written.

docs/decisions/README.md[30-32]
docs/decisions/0000-template.md[6-6]
docs/decisions/README.md[65-67]

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 ADR template and README disagree on the expected decision filename pattern for supersedence links (`NNNN-title.md` vs `NNNN-short-title.md`). This can cause inconsistent file naming and incorrect/inconsistent links across ADRs.
## Issue Context
- README instructs authors to create ADRs as `NNNN-short-title.md`.
- Template’s status-line comment suggests `Superseded by [NNNN](NNNN-title.md)`.
## Fix Focus Areas
- docs/decisions/0000-template.md[6-6]
- docs/decisions/README.md[30-32]
- docs/decisions/README.md[65-67]
## Suggested fix
- Update the template’s supersedence example to use `NNNN-short-title.md` (or a neutral placeholder matching the README’s convention).
- Update the README’s `Superseded by [NNNN](...)` example to show the same filename pattern explicitly (e.g., `Superseded by [NNNN](NNNN-short-title.md)`).

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

---

[qodo-code-review]

PR Summary by Qodo

Add ADR process and template under docs/decisions
📝 Documentation🕐 10-20 Minutes

Walkthroughs

Description

• Introduce a Design Decision Record (ADR) log for cross-binding Selenium decisions
• Document proposal/approval workflow (PR discussion + TLC consensus; merge equals acceptance)
• Provide a reusable ADR template including per-binding convergence status tracking

Diagram

flowchart TD
C(["Contributor"]) --> T["Copy template"] --> PR["Open PR (Proposed)"] --> TLC{"TLC consensus"} --> M["Merge PR"] --> ADR["Decision record"] --> B["Update binding status"]
subgraph Legend
direction LR
_term(["Terminator"]) ~~~ _proc["Process"] ~~~ _dec{"Decision"}
end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Host ADRs in selenium.dev (website repo)

• ➕ Immediate public discoverability and site navigation/search integration
• ➕ Keeps governance/process docs near other public-facing documentation
• ➖ Weakens the “merge equals acceptance” workflow tied to core repo reviews
• ➖ Harder to keep contributor-targeted process close to where changes are made

2. Use GitHub Discussions/issues as the canonical decision record

• ➕ Native threading and visibility; easy to reference and participate
• ➕ No need to maintain a file format/template
• ➖ Harder to keep a concise, immutable, durable summary of the final decision
• ➖ More risk of re-litigating settled questions across multiple threads

3. Adopt MADR/Nygard format verbatim (no binding-status table)

• ➕ Maximum familiarity and portability to other ADR tooling
• ➕ Less bespoke structure to maintain
• ➖ Doesn’t directly address Selenium’s multi-binding convergence tracking needs
• ➖ Status per binding would likely drift into external trackers or PR comments

Recommendation: The PR’s approach (ADRs in-repo, merge-as-acceptance, and a per-binding status table) is the best fit for Selenium’s cross-binding governance: it keeps the canonical record in the review workflow contributors already use, while explicitly tracking convergence across languages. The main thing to validate in review is whether the approval/consensus wording matches current TLC expectations.

File Changes

Documentation (2)

0000-template.mdAdd ADR template with binding-status table+56/-0

Add ADR template with binding-status table

• Introduces a numbered decision record template based on common ADR formats. Includes required sections (Context, Decision, Considered options, Consequences) and adds a dedicated per-binding status table to track convergence across Selenium bindings.

docs/decisions/0000-template.md

---

README.mdDocument ADR scope, workflow, and TLC approval rules+71/-0

Document ADR scope, workflow, and TLC approval rules

• Defines what qualifies for a cross-binding decision record and what does not. Specifies the end-to-end process (propose via PR, discuss in PR/TLC, merge as acceptance/rejection, and binding implementation tracking) plus approval/immutability and numbering rules.

docs/decisions/README.md

---

[qodo-code-review]

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

[titusfortner]

💥 What does this PR do?

Adds docs/decisions/ — a lightweight process for recording design decisions that apply across bindings (API shape, cross-binding semantics, deprecation commitments), plus the template for writing one. Decisions are proposed as PRs, discussed on the PR thread and at TLC meetings, and accepted by TLC consensus; the merged file is the canonical record, so settled questions get answered with a link instead of being re-litigated.

🔧 Implementation Notes

• Format is based on MADR/Nygard ADRs with one Selenium-specific addition: a per-binding status table so convergence across the five bindings is tracked in the record itself.
• These live in trunk rather than the website repo because the audience is contributors and the merge-is-acceptance process depends on the code-review flow. They can be rendered to selenium.dev later without moving the source of truth.

🤖 AI assistance

• AI assisted (complete below)
  • Tool(s): Claude Code
  • What was generated: Initial drafts of the README and template, revised through discussion and review
  • I reviewed all AI output and can explain the change

💡 Additional Considerations

• This PR follows the process it introduces: feedback is encouraged from all contributors; it merges by TLC consensus — a majority of TLC members responding with no unresolved objections, after at least one week open and discussion at a TLC meeting — with the Selenium Project Lead performing the merge. Merging adopts the process.

🔄 Types of changes

• Documentation (contributor process)

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1)📘 Rule violations (0)

1. Filename convention mismatch 🐞 Bug⚙ Maintainability

Description

The ADR template’s supersedence example points to NNNN-title.md, but the README standardizes
decision filenames as NNNN-short-title.md, creating conflicting guidance that can lead to
inconsistent ADR filenames/links when contributors copy the template verbatim.

Code

docs/decisions/0000-template.md[6]

+- Status: Proposed <!-- Proposed | Accepted | Rejected | Superseded by [NNNN](NNNN-title.md) -->

Evidence

The README defines the canonical ADR filename format as NNNN-short-title.md, while the template’s
status-line example uses a different filename (NNNN-title.md), so the two new docs conflict on how
supersedence links should be written.

docs/decisions/README.md[30-32]
docs/decisions/0000-template.md[6-6]
docs/decisions/README.md[65-67]

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 ADR template and README disagree on the expected decision filename pattern for supersedence links (`NNNN-title.md` vs `NNNN-short-title.md`). This can cause inconsistent file naming and incorrect/inconsistent links across ADRs.
## Issue Context
- README instructs authors to create ADRs as `NNNN-short-title.md`.
- Template’s status-line comment suggests `Superseded by [NNNN](NNNN-title.md)`.
## Fix Focus Areas
- docs/decisions/0000-template.md[6-6]
- docs/decisions/README.md[30-32]
- docs/decisions/README.md[65-67]
## Suggested fix
- Update the template’s supersedence example to use `NNNN-short-title.md` (or a neutral placeholder matching the README’s convention).
- Update the README’s `Superseded by [NNNN](...)` example to show the same filename pattern explicitly (e.g., `Superseded by [NNNN](NNNN-short-title.md)`).

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

---

Previous review results

Review updated until commit 9288155

Results up to commit 9554f29

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

1. Filename convention mismatch 🐞 Bug⚙ Maintainability

Description

The ADR template’s supersedence example points to NNNN-title.md, but the README standardizes
decision filenames as NNNN-short-title.md, creating conflicting guidance that can lead to
inconsistent ADR filenames/links when contributors copy the template verbatim.

Code

docs/decisions/0000-template.md[6]

+- Status: Proposed <!-- Proposed | Accepted | Rejected | Superseded by [NNNN](NNNN-title.md) -->

Evidence

The README defines the canonical ADR filename format as NNNN-short-title.md, while the template’s
status-line example uses a different filename (NNNN-title.md), so the two new docs conflict on how
supersedence links should be written.

docs/decisions/README.md[30-32]
docs/decisions/0000-template.md[6-6]
docs/decisions/README.md[65-67]

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 ADR template and README disagree on the expected decision filename pattern for supersedence links (`NNNN-title.md` vs `NNNN-short-title.md`). This can cause inconsistent file naming and incorrect/inconsistent links across ADRs.
## Issue Context
- README instructs authors to create ADRs as `NNNN-short-title.md`.
- Template’s status-line comment suggests `Superseded by [NNNN](NNNN-title.md)`.
## Fix Focus Areas
- docs/decisions/0000-template.md[6-6]
- docs/decisions/README.md[30-32]
- docs/decisions/README.md[65-67]
## Suggested fix
- Update the template’s supersedence example to use `NNNN-short-title.md` (or a neutral placeholder matching the README’s convention).
- Update the README’s `Superseded by [NNNN](...)` example to show the same filename pattern explicitly (e.g., `Superseded by [NNNN](NNNN-short-title.md)`).

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

---

[qodo-code-review]

PR Summary by Qodo

Add ADR process and template under docs/decisions
📝 Documentation🕐 10-20 Minutes

Walkthroughs

Description

• Introduce a Design Decision Record (ADR) log for cross-binding Selenium decisions
• Document proposal/approval workflow (PR discussion + TLC consensus; merge equals acceptance)
• Provide a reusable ADR template including per-binding convergence status tracking

Diagram

flowchart TD
C(["Contributor"]) --> T["Copy template"] --> PR["Open PR (Proposed)"] --> TLC{"TLC consensus"} --> M["Merge PR"] --> ADR["Decision record"] --> B["Update binding status"]
subgraph Legend
direction LR
_term(["Terminator"]) ~~~ _proc["Process"] ~~~ _dec{"Decision"}
end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Host ADRs in selenium.dev (website repo)

• ➕ Immediate public discoverability and site navigation/search integration
• ➕ Keeps governance/process docs near other public-facing documentation
• ➖ Weakens the “merge equals acceptance” workflow tied to core repo reviews
• ➖ Harder to keep contributor-targeted process close to where changes are made

2. Use GitHub Discussions/issues as the canonical decision record

• ➕ Native threading and visibility; easy to reference and participate
• ➕ No need to maintain a file format/template
• ➖ Harder to keep a concise, immutable, durable summary of the final decision
• ➖ More risk of re-litigating settled questions across multiple threads

3. Adopt MADR/Nygard format verbatim (no binding-status table)

• ➕ Maximum familiarity and portability to other ADR tooling
• ➕ Less bespoke structure to maintain
• ➖ Doesn’t directly address Selenium’s multi-binding convergence tracking needs
• ➖ Status per binding would likely drift into external trackers or PR comments

Recommendation: The PR’s approach (ADRs in-repo, merge-as-acceptance, and a per-binding status table) is the best fit for Selenium’s cross-binding governance: it keeps the canonical record in the review workflow contributors already use, while explicitly tracking convergence across languages. The main thing to validate in review is whether the approval/consensus wording matches current TLC expectations.

File Changes

Documentation (2)

0000-template.mdAdd ADR template with binding-status table+56/-0

Add ADR template with binding-status table

• Introduces a numbered decision record template based on common ADR formats. Includes required sections (Context, Decision, Considered options, Consequences) and adds a dedicated per-binding status table to track convergence across Selenium bindings.

docs/decisions/0000-template.md

---

README.mdDocument ADR scope, workflow, and TLC approval rules+71/-0

Document ADR scope, workflow, and TLC approval rules

• Defines what qualifies for a cross-binding decision record and what does not. Specifies the end-to-end process (propose via PR, discuss in PR/TLC, merge as acceptance/rejection, and binding implementation tracking) plus approval/immutability and numbering rules.

docs/decisions/README.md

---

[qodo-code-review]

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

[titusfortner]

💥 What does this PR do?

Adds docs/decisions/ — a lightweight process for recording design decisions that apply across bindings (API shape, cross-binding semantics, deprecation commitments), plus the template for writing one. Decisions are proposed as PRs, discussed on the PR thread and at TLC meetings, and accepted by TLC consensus; the merged file is the canonical record, so settled questions get answered with a link instead of being re-litigated.

🔧 Implementation Notes

• Format is based on MADR/Nygard ADRs with one Selenium-specific addition: a per-binding status table so convergence across the five bindings is tracked in the record itself.
• These live in trunk rather than the website repo because the audience is contributors and the merge-is-acceptance process depends on the code-review flow. They can be rendered to selenium.dev later without moving the source of truth.

🤖 AI assistance

• AI assisted (complete below)
  • Tool(s): Claude Code
  • What was generated: Initial drafts of the README and template, revised through discussion and review
  • I reviewed all AI output and can explain the change

💡 Additional Considerations

• This PR follows the process it introduces: feedback is encouraged from all contributors; it merges by TLC consensus — a majority of TLC members responding with no unresolved objections, after at least one week open and discussion at a TLC meeting — with the Selenium Project Lead performing the merge. Merging adopts the process.

🔄 Types of changes

• Documentation (contributor process)

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1)📘 Rule violations (0)

1. Filename convention mismatch 🐞 Bug⚙ Maintainability

Description

The ADR template’s supersedence example points to NNNN-title.md, but the README standardizes
decision filenames as NNNN-short-title.md, creating conflicting guidance that can lead to
inconsistent ADR filenames/links when contributors copy the template verbatim.

Code

docs/decisions/0000-template.md[6]

+- Status: Proposed <!-- Proposed | Accepted | Rejected | Superseded by [NNNN](NNNN-title.md) -->

Evidence

The README defines the canonical ADR filename format as NNNN-short-title.md, while the template’s
status-line example uses a different filename (NNNN-title.md), so the two new docs conflict on how
supersedence links should be written.

docs/decisions/README.md[30-32]
docs/decisions/0000-template.md[6-6]
docs/decisions/README.md[65-67]

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 ADR template and README disagree on the expected decision filename pattern for supersedence links (`NNNN-title.md` vs `NNNN-short-title.md`). This can cause inconsistent file naming and incorrect/inconsistent links across ADRs.
## Issue Context
- README instructs authors to create ADRs as `NNNN-short-title.md`.
- Template’s status-line comment suggests `Superseded by [NNNN](NNNN-title.md)`.
## Fix Focus Areas
- docs/decisions/0000-template.md[6-6]
- docs/decisions/README.md[30-32]
- docs/decisions/README.md[65-67]
## Suggested fix
- Update the template’s supersedence example to use `NNNN-short-title.md` (or a neutral placeholder matching the README’s convention).
- Update the README’s `Superseded by [NNNN](...)` example to show the same filename pattern explicitly (e.g., `Superseded by [NNNN](NNNN-short-title.md)`).

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

---

Previous review results

Review updated until commit 9288155

Results up to commit 9554f29

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

1. Filename convention mismatch 🐞 Bug⚙ Maintainability

Description

The ADR template’s supersedence example points to NNNN-title.md, but the README standardizes
decision filenames as NNNN-short-title.md, creating conflicting guidance that can lead to
inconsistent ADR filenames/links when contributors copy the template verbatim.

Code

docs/decisions/0000-template.md[6]

+- Status: Proposed <!-- Proposed | Accepted | Rejected | Superseded by [NNNN](NNNN-title.md) -->

Evidence

The README defines the canonical ADR filename format as NNNN-short-title.md, while the template’s
status-line example uses a different filename (NNNN-title.md), so the two new docs conflict on how
supersedence links should be written.

docs/decisions/README.md[30-32]
docs/decisions/0000-template.md[6-6]
docs/decisions/README.md[65-67]

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 ADR template and README disagree on the expected decision filename pattern for supersedence links (`NNNN-title.md` vs `NNNN-short-title.md`). This can cause inconsistent file naming and incorrect/inconsistent links across ADRs.
## Issue Context
- README instructs authors to create ADRs as `NNNN-short-title.md`.
- Template’s status-line comment suggests `Superseded by [NNNN](NNNN-title.md)`.
## Fix Focus Areas
- docs/decisions/0000-template.md[6-6]
- docs/decisions/README.md[30-32]
- docs/decisions/README.md[65-67]
## Suggested fix
- Update the template’s supersedence example to use `NNNN-short-title.md` (or a neutral placeholder matching the README’s convention).
- Update the README’s `Superseded by [NNNN](...)` example to show the same filename pattern explicitly (e.g., `Superseded by [NNNN](NNNN-short-title.md)`).

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

---

[qodo-code-review]

PR Summary by Qodo

Add ADR process and template under docs/decisions
📝 Documentation🕐 10-20 Minutes

Walkthroughs

Description

• Introduce a Design Decision Record (ADR) log for cross-binding Selenium decisions
• Document proposal/approval workflow (PR discussion + TLC consensus; merge equals acceptance)
• Provide a reusable ADR template including per-binding convergence status tracking

Diagram

flowchart TD
C(["Contributor"]) --> T["Copy template"] --> PR["Open PR (Proposed)"] --> TLC{"TLC consensus"} --> M["Merge PR"] --> ADR["Decision record"] --> B["Update binding status"]
subgraph Legend
direction LR
_term(["Terminator"]) ~~~ _proc["Process"] ~~~ _dec{"Decision"}
end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Host ADRs in selenium.dev (website repo)

• ➕ Immediate public discoverability and site navigation/search integration
• ➕ Keeps governance/process docs near other public-facing documentation
• ➖ Weakens the “merge equals acceptance” workflow tied to core repo reviews
• ➖ Harder to keep contributor-targeted process close to where changes are made

2. Use GitHub Discussions/issues as the canonical decision record

• ➕ Native threading and visibility; easy to reference and participate
• ➕ No need to maintain a file format/template
• ➖ Harder to keep a concise, immutable, durable summary of the final decision
• ➖ More risk of re-litigating settled questions across multiple threads

3. Adopt MADR/Nygard format verbatim (no binding-status table)

• ➕ Maximum familiarity and portability to other ADR tooling
• ➕ Less bespoke structure to maintain
• ➖ Doesn’t directly address Selenium’s multi-binding convergence tracking needs
• ➖ Status per binding would likely drift into external trackers or PR comments

Recommendation: The PR’s approach (ADRs in-repo, merge-as-acceptance, and a per-binding status table) is the best fit for Selenium’s cross-binding governance: it keeps the canonical record in the review workflow contributors already use, while explicitly tracking convergence across languages. The main thing to validate in review is whether the approval/consensus wording matches current TLC expectations.

File Changes

Documentation (2)

0000-template.mdAdd ADR template with binding-status table+56/-0

Add ADR template with binding-status table

• Introduces a numbered decision record template based on common ADR formats. Includes required sections (Context, Decision, Considered options, Consequences) and adds a dedicated per-binding status table to track convergence across Selenium bindings.

docs/decisions/0000-template.md

---

README.mdDocument ADR scope, workflow, and TLC approval rules+71/-0

Document ADR scope, workflow, and TLC approval rules

• Defines what qualifies for a cross-binding decision record and what does not. Specifies the end-to-end process (propose via PR, discuss in PR/TLC, merge as acceptance/rejection, and binding implementation tracking) plus approval/immutability and numbering rules.

docs/decisions/README.md

---

[qodo-code-review]

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

[titusfortner]

💥 What does this PR do?

Adds docs/decisions/ — a lightweight process for recording design decisions that apply across bindings (API shape, cross-binding semantics, deprecation commitments), plus the template for writing one. Decisions are proposed as PRs, discussed on the PR thread and at TLC meetings, and accepted by TLC consensus; the merged file is the canonical record, so settled questions get answered with a link instead of being re-litigated.

🔧 Implementation Notes

• Format is based on MADR/Nygard ADRs with one Selenium-specific addition: a per-binding status table so convergence across the five bindings is tracked in the record itself.
• These live in trunk rather than the website repo because the audience is contributors and the merge-is-acceptance process depends on the code-review flow. They can be rendered to selenium.dev later without moving the source of truth.

🤖 AI assistance

• AI assisted (complete below)
  • Tool(s): Claude Code
  • What was generated: Initial drafts of the README and template, revised through discussion and review
  • I reviewed all AI output and can explain the change

💡 Additional Considerations

• This PR follows the process it introduces: feedback is encouraged from all contributors; it merges by TLC consensus — a majority of TLC members responding with no unresolved objections, after at least one week open and discussion at a TLC meeting — with the Selenium Project Lead performing the merge. Merging adopts the process.

🔄 Types of changes

• Documentation (contributor process)

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1)📘 Rule violations (0)

1. Filename convention mismatch 🐞 Bug⚙ Maintainability

Description

The ADR template’s supersedence example points to NNNN-title.md, but the README standardizes
decision filenames as NNNN-short-title.md, creating conflicting guidance that can lead to
inconsistent ADR filenames/links when contributors copy the template verbatim.

Code

docs/decisions/0000-template.md[6]

+- Status: Proposed <!-- Proposed | Accepted | Rejected | Superseded by [NNNN](NNNN-title.md) -->

Evidence

The README defines the canonical ADR filename format as NNNN-short-title.md, while the template’s
status-line example uses a different filename (NNNN-title.md), so the two new docs conflict on how
supersedence links should be written.

docs/decisions/README.md[30-32]
docs/decisions/0000-template.md[6-6]
docs/decisions/README.md[65-67]

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 ADR template and README disagree on the expected decision filename pattern for supersedence links (`NNNN-title.md` vs `NNNN-short-title.md`). This can cause inconsistent file naming and incorrect/inconsistent links across ADRs.
## Issue Context
- README instructs authors to create ADRs as `NNNN-short-title.md`.
- Template’s status-line comment suggests `Superseded by [NNNN](NNNN-title.md)`.
## Fix Focus Areas
- docs/decisions/0000-template.md[6-6]
- docs/decisions/README.md[30-32]
- docs/decisions/README.md[65-67]
## Suggested fix
- Update the template’s supersedence example to use `NNNN-short-title.md` (or a neutral placeholder matching the README’s convention).
- Update the README’s `Superseded by [NNNN](...)` example to show the same filename pattern explicitly (e.g., `Superseded by [NNNN](NNNN-short-title.md)`).

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

---

Previous review results

Review updated until commit 9288155

Results up to commit 9554f29

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

1. Filename convention mismatch 🐞 Bug⚙ Maintainability

Description

The ADR template’s supersedence example points to NNNN-title.md, but the README standardizes
decision filenames as NNNN-short-title.md, creating conflicting guidance that can lead to
inconsistent ADR filenames/links when contributors copy the template verbatim.

Code

docs/decisions/0000-template.md[6]

+- Status: Proposed <!-- Proposed | Accepted | Rejected | Superseded by [NNNN](NNNN-title.md) -->

Evidence

The README defines the canonical ADR filename format as NNNN-short-title.md, while the template’s
status-line example uses a different filename (NNNN-title.md), so the two new docs conflict on how
supersedence links should be written.

docs/decisions/README.md[30-32]
docs/decisions/0000-template.md[6-6]
docs/decisions/README.md[65-67]

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 ADR template and README disagree on the expected decision filename pattern for supersedence links (`NNNN-title.md` vs `NNNN-short-title.md`). This can cause inconsistent file naming and incorrect/inconsistent links across ADRs.
## Issue Context
- README instructs authors to create ADRs as `NNNN-short-title.md`.
- Template’s status-line comment suggests `Superseded by [NNNN](NNNN-title.md)`.
## Fix Focus Areas
- docs/decisions/0000-template.md[6-6]
- docs/decisions/README.md[30-32]
- docs/decisions/README.md[65-67]
## Suggested fix
- Update the template’s supersedence example to use `NNNN-short-title.md` (or a neutral placeholder matching the README’s convention).
- Update the README’s `Superseded by [NNNN](...)` example to show the same filename pattern explicitly (e.g., `Superseded by [NNNN](NNNN-short-title.md)`).

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

---

[qodo-code-review]

PR Summary by Qodo

Add ADR process and template under docs/decisions
📝 Documentation🕐 10-20 Minutes

Walkthroughs

Description

• Introduce a Design Decision Record (ADR) log for cross-binding Selenium decisions
• Document proposal/approval workflow (PR discussion + TLC consensus; merge equals acceptance)
• Provide a reusable ADR template including per-binding convergence status tracking

Diagram

flowchart TD
C(["Contributor"]) --> T["Copy template"] --> PR["Open PR (Proposed)"] --> TLC{"TLC consensus"} --> M["Merge PR"] --> ADR["Decision record"] --> B["Update binding status"]
subgraph Legend
direction LR
_term(["Terminator"]) ~~~ _proc["Process"] ~~~ _dec{"Decision"}
end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Host ADRs in selenium.dev (website repo)

• ➕ Immediate public discoverability and site navigation/search integration
• ➕ Keeps governance/process docs near other public-facing documentation
• ➖ Weakens the “merge equals acceptance” workflow tied to core repo reviews
• ➖ Harder to keep contributor-targeted process close to where changes are made

2. Use GitHub Discussions/issues as the canonical decision record

• ➕ Native threading and visibility; easy to reference and participate
• ➕ No need to maintain a file format/template
• ➖ Harder to keep a concise, immutable, durable summary of the final decision
• ➖ More risk of re-litigating settled questions across multiple threads

3. Adopt MADR/Nygard format verbatim (no binding-status table)

• ➕ Maximum familiarity and portability to other ADR tooling
• ➕ Less bespoke structure to maintain
• ➖ Doesn’t directly address Selenium’s multi-binding convergence tracking needs
• ➖ Status per binding would likely drift into external trackers or PR comments

Recommendation: The PR’s approach (ADRs in-repo, merge-as-acceptance, and a per-binding status table) is the best fit for Selenium’s cross-binding governance: it keeps the canonical record in the review workflow contributors already use, while explicitly tracking convergence across languages. The main thing to validate in review is whether the approval/consensus wording matches current TLC expectations.

File Changes

Documentation (2)

0000-template.mdAdd ADR template with binding-status table+56/-0

Add ADR template with binding-status table

• Introduces a numbered decision record template based on common ADR formats. Includes required sections (Context, Decision, Considered options, Consequences) and adds a dedicated per-binding status table to track convergence across Selenium bindings.

docs/decisions/0000-template.md

---

README.mdDocument ADR scope, workflow, and TLC approval rules+71/-0

Document ADR scope, workflow, and TLC approval rules

• Defines what qualifies for a cross-binding decision record and what does not. Specifies the end-to-end process (propose via PR, discuss in PR/TLC, merge as acceptance/rejection, and binding implementation tracking) plus approval/immutability and numbering rules.

docs/decisions/README.md

---

[qodo-code-review]

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

[titusfortner]

💥 What does this PR do?

Adds docs/decisions/ — a lightweight process for recording design decisions that apply across bindings (API shape, cross-binding semantics, deprecation commitments), plus the template for writing one. Decisions are proposed as PRs, discussed on the PR thread and at TLC meetings, and accepted by TLC consensus; the merged file is the canonical record, so settled questions get answered with a link instead of being re-litigated.

🔧 Implementation Notes

• Format is based on MADR/Nygard ADRs with one Selenium-specific addition: a per-binding status table so convergence across the five bindings is tracked in the record itself.
• These live in trunk rather than the website repo because the audience is contributors and the merge-is-acceptance process depends on the code-review flow. They can be rendered to selenium.dev later without moving the source of truth.

🤖 AI assistance

• AI assisted (complete below)
  • Tool(s): Claude Code
  • What was generated: Initial drafts of the README and template, revised through discussion and review
  • I reviewed all AI output and can explain the change

💡 Additional Considerations

• This PR follows the process it introduces: feedback is encouraged from all contributors; it merges by TLC consensus — a majority of TLC members responding with no unresolved objections, after at least one week open and discussion at a TLC meeting — with the Selenium Project Lead performing the merge. Merging adopts the process.

🔄 Types of changes

• Documentation (contributor process)

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1)📘 Rule violations (0)

1. Filename convention mismatch 🐞 Bug⚙ Maintainability

Description

The ADR template’s supersedence example points to NNNN-title.md, but the README standardizes
decision filenames as NNNN-short-title.md, creating conflicting guidance that can lead to
inconsistent ADR filenames/links when contributors copy the template verbatim.

Code

docs/decisions/0000-template.md[6]

+- Status: Proposed <!-- Proposed | Accepted | Rejected | Superseded by [NNNN](NNNN-title.md) -->

Evidence

The README defines the canonical ADR filename format as NNNN-short-title.md, while the template’s
status-line example uses a different filename (NNNN-title.md), so the two new docs conflict on how
supersedence links should be written.

docs/decisions/README.md[30-32]
docs/decisions/0000-template.md[6-6]
docs/decisions/README.md[65-67]

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 ADR template and README disagree on the expected decision filename pattern for supersedence links (`NNNN-title.md` vs `NNNN-short-title.md`). This can cause inconsistent file naming and incorrect/inconsistent links across ADRs.
## Issue Context
- README instructs authors to create ADRs as `NNNN-short-title.md`.
- Template’s status-line comment suggests `Superseded by [NNNN](NNNN-title.md)`.
## Fix Focus Areas
- docs/decisions/0000-template.md[6-6]
- docs/decisions/README.md[30-32]
- docs/decisions/README.md[65-67]
## Suggested fix
- Update the template’s supersedence example to use `NNNN-short-title.md` (or a neutral placeholder matching the README’s convention).
- Update the README’s `Superseded by [NNNN](...)` example to show the same filename pattern explicitly (e.g., `Superseded by [NNNN](NNNN-short-title.md)`).

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

---

Previous review results

Review updated until commit 9288155

Results up to commit 9554f29

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

1. Filename convention mismatch 🐞 Bug⚙ Maintainability

Description

The ADR template’s supersedence example points to NNNN-title.md, but the README standardizes
decision filenames as NNNN-short-title.md, creating conflicting guidance that can lead to
inconsistent ADR filenames/links when contributors copy the template verbatim.

Code

docs/decisions/0000-template.md[6]

+- Status: Proposed <!-- Proposed | Accepted | Rejected | Superseded by [NNNN](NNNN-title.md) -->

Evidence

The README defines the canonical ADR filename format as NNNN-short-title.md, while the template’s
status-line example uses a different filename (NNNN-title.md), so the two new docs conflict on how
supersedence links should be written.

docs/decisions/README.md[30-32]
docs/decisions/0000-template.md[6-6]
docs/decisions/README.md[65-67]

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 ADR template and README disagree on the expected decision filename pattern for supersedence links (`NNNN-title.md` vs `NNNN-short-title.md`). This can cause inconsistent file naming and incorrect/inconsistent links across ADRs.
## Issue Context
- README instructs authors to create ADRs as `NNNN-short-title.md`.
- Template’s status-line comment suggests `Superseded by [NNNN](NNNN-title.md)`.
## Fix Focus Areas
- docs/decisions/0000-template.md[6-6]
- docs/decisions/README.md[30-32]
- docs/decisions/README.md[65-67]
## Suggested fix
- Update the template’s supersedence example to use `NNNN-short-title.md` (or a neutral placeholder matching the README’s convention).
- Update the README’s `Superseded by [NNNN](...)` example to show the same filename pattern explicitly (e.g., `Superseded by [NNNN](NNNN-short-title.md)`).

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

---

[qodo-code-review]

PR Summary by Qodo

Add ADR process and template under docs/decisions
📝 Documentation🕐 10-20 Minutes

Walkthroughs

Description

• Introduce a Design Decision Record (ADR) log for cross-binding Selenium decisions
• Document proposal/approval workflow (PR discussion + TLC consensus; merge equals acceptance)
• Provide a reusable ADR template including per-binding convergence status tracking

Diagram

flowchart TD
C(["Contributor"]) --> T["Copy template"] --> PR["Open PR (Proposed)"] --> TLC{"TLC consensus"} --> M["Merge PR"] --> ADR["Decision record"] --> B["Update binding status"]
subgraph Legend
direction LR
_term(["Terminator"]) ~~~ _proc["Process"] ~~~ _dec{"Decision"}
end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Host ADRs in selenium.dev (website repo)

• ➕ Immediate public discoverability and site navigation/search integration
• ➕ Keeps governance/process docs near other public-facing documentation
• ➖ Weakens the “merge equals acceptance” workflow tied to core repo reviews
• ➖ Harder to keep contributor-targeted process close to where changes are made

2. Use GitHub Discussions/issues as the canonical decision record

• ➕ Native threading and visibility; easy to reference and participate
• ➕ No need to maintain a file format/template
• ➖ Harder to keep a concise, immutable, durable summary of the final decision
• ➖ More risk of re-litigating settled questions across multiple threads

3. Adopt MADR/Nygard format verbatim (no binding-status table)

• ➕ Maximum familiarity and portability to other ADR tooling
• ➕ Less bespoke structure to maintain
• ➖ Doesn’t directly address Selenium’s multi-binding convergence tracking needs
• ➖ Status per binding would likely drift into external trackers or PR comments

Recommendation: The PR’s approach (ADRs in-repo, merge-as-acceptance, and a per-binding status table) is the best fit for Selenium’s cross-binding governance: it keeps the canonical record in the review workflow contributors already use, while explicitly tracking convergence across languages. The main thing to validate in review is whether the approval/consensus wording matches current TLC expectations.

File Changes

Documentation (2)

0000-template.mdAdd ADR template with binding-status table+56/-0

Add ADR template with binding-status table

• Introduces a numbered decision record template based on common ADR formats. Includes required sections (Context, Decision, Considered options, Consequences) and adds a dedicated per-binding status table to track convergence across Selenium bindings.

docs/decisions/0000-template.md

---

README.mdDocument ADR scope, workflow, and TLC approval rules+71/-0

Document ADR scope, workflow, and TLC approval rules

• Defines what qualifies for a cross-binding decision record and what does not. Specifies the end-to-end process (propose via PR, discuss in PR/TLC, merge as acceptance/rejection, and binding implementation tracking) plus approval/immutability and numbering rules.

docs/decisions/README.md

---

[qodo-code-review]

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

[titusfortner]

💥 What does this PR do?

Adds docs/decisions/ — a lightweight process for recording design decisions that apply across bindings (API shape, cross-binding semantics, deprecation commitments), plus the template for writing one. Decisions are proposed as PRs, discussed on the PR thread and at TLC meetings, and accepted by TLC consensus; the merged file is the canonical record, so settled questions get answered with a link instead of being re-litigated.

🔧 Implementation Notes

• Format is based on MADR/Nygard ADRs with one Selenium-specific addition: a per-binding status table so convergence across the five bindings is tracked in the record itself.
• These live in trunk rather than the website repo because the audience is contributors and the merge-is-acceptance process depends on the code-review flow. They can be rendered to selenium.dev later without moving the source of truth.

🤖 AI assistance

• AI assisted (complete below)
  • Tool(s): Claude Code
  • What was generated: Initial drafts of the README and template, revised through discussion and review
  • I reviewed all AI output and can explain the change

💡 Additional Considerations

• This PR follows the process it introduces: feedback is encouraged from all contributors; it merges by TLC consensus — a majority of TLC members responding with no unresolved objections, after at least one week open and discussion at a TLC meeting — with the Selenium Project Lead performing the merge. Merging adopts the process.

🔄 Types of changes

• Documentation (contributor process)

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1)📘 Rule violations (0)

1. Filename convention mismatch 🐞 Bug⚙ Maintainability

Description

The ADR template’s supersedence example points to NNNN-title.md, but the README standardizes
decision filenames as NNNN-short-title.md, creating conflicting guidance that can lead to
inconsistent ADR filenames/links when contributors copy the template verbatim.

Code

docs/decisions/0000-template.md[6]

+- Status: Proposed <!-- Proposed | Accepted | Rejected | Superseded by [NNNN](NNNN-title.md) -->

Evidence

The README defines the canonical ADR filename format as NNNN-short-title.md, while the template’s
status-line example uses a different filename (NNNN-title.md), so the two new docs conflict on how
supersedence links should be written.

docs/decisions/README.md[30-32]
docs/decisions/0000-template.md[6-6]
docs/decisions/README.md[65-67]

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 ADR template and README disagree on the expected decision filename pattern for supersedence links (`NNNN-title.md` vs `NNNN-short-title.md`). This can cause inconsistent file naming and incorrect/inconsistent links across ADRs.
## Issue Context
- README instructs authors to create ADRs as `NNNN-short-title.md`.
- Template’s status-line comment suggests `Superseded by [NNNN](NNNN-title.md)`.
## Fix Focus Areas
- docs/decisions/0000-template.md[6-6]
- docs/decisions/README.md[30-32]
- docs/decisions/README.md[65-67]
## Suggested fix
- Update the template’s supersedence example to use `NNNN-short-title.md` (or a neutral placeholder matching the README’s convention).
- Update the README’s `Superseded by [NNNN](...)` example to show the same filename pattern explicitly (e.g., `Superseded by [NNNN](NNNN-short-title.md)`).

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

---

Previous review results

Review updated until commit 9288155

Results up to commit 9554f29

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

1. Filename convention mismatch 🐞 Bug⚙ Maintainability

Description

The ADR template’s supersedence example points to NNNN-title.md, but the README standardizes
decision filenames as NNNN-short-title.md, creating conflicting guidance that can lead to
inconsistent ADR filenames/links when contributors copy the template verbatim.

Code

docs/decisions/0000-template.md[6]

+- Status: Proposed <!-- Proposed | Accepted | Rejected | Superseded by [NNNN](NNNN-title.md) -->

Evidence

The README defines the canonical ADR filename format as NNNN-short-title.md, while the template’s
status-line example uses a different filename (NNNN-title.md), so the two new docs conflict on how
supersedence links should be written.

docs/decisions/README.md[30-32]
docs/decisions/0000-template.md[6-6]
docs/decisions/README.md[65-67]

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 ADR template and README disagree on the expected decision filename pattern for supersedence links (`NNNN-title.md` vs `NNNN-short-title.md`). This can cause inconsistent file naming and incorrect/inconsistent links across ADRs.
## Issue Context
- README instructs authors to create ADRs as `NNNN-short-title.md`.
- Template’s status-line comment suggests `Superseded by [NNNN](NNNN-title.md)`.
## Fix Focus Areas
- docs/decisions/0000-template.md[6-6]
- docs/decisions/README.md[30-32]
- docs/decisions/README.md[65-67]
## Suggested fix
- Update the template’s supersedence example to use `NNNN-short-title.md` (or a neutral placeholder matching the README’s convention).
- Update the README’s `Superseded by [NNNN](...)` example to show the same filename pattern explicitly (e.g., `Superseded by [NNNN](NNNN-short-title.md)`).

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

---

[qodo-code-review]

PR Summary by Qodo

Add ADR process and template under docs/decisions
📝 Documentation🕐 10-20 Minutes

Walkthroughs

Description

• Introduce a Design Decision Record (ADR) log for cross-binding Selenium decisions
• Document proposal/approval workflow (PR discussion + TLC consensus; merge equals acceptance)
• Provide a reusable ADR template including per-binding convergence status tracking

Diagram

flowchart TD
C(["Contributor"]) --> T["Copy template"] --> PR["Open PR (Proposed)"] --> TLC{"TLC consensus"} --> M["Merge PR"] --> ADR["Decision record"] --> B["Update binding status"]
subgraph Legend
direction LR
_term(["Terminator"]) ~~~ _proc["Process"] ~~~ _dec{"Decision"}
end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Host ADRs in selenium.dev (website repo)

• ➕ Immediate public discoverability and site navigation/search integration
• ➕ Keeps governance/process docs near other public-facing documentation
• ➖ Weakens the “merge equals acceptance” workflow tied to core repo reviews
• ➖ Harder to keep contributor-targeted process close to where changes are made

2. Use GitHub Discussions/issues as the canonical decision record

• ➕ Native threading and visibility; easy to reference and participate
• ➕ No need to maintain a file format/template
• ➖ Harder to keep a concise, immutable, durable summary of the final decision
• ➖ More risk of re-litigating settled questions across multiple threads

3. Adopt MADR/Nygard format verbatim (no binding-status table)

• ➕ Maximum familiarity and portability to other ADR tooling
• ➕ Less bespoke structure to maintain
• ➖ Doesn’t directly address Selenium’s multi-binding convergence tracking needs
• ➖ Status per binding would likely drift into external trackers or PR comments

Recommendation: The PR’s approach (ADRs in-repo, merge-as-acceptance, and a per-binding status table) is the best fit for Selenium’s cross-binding governance: it keeps the canonical record in the review workflow contributors already use, while explicitly tracking convergence across languages. The main thing to validate in review is whether the approval/consensus wording matches current TLC expectations.

File Changes

Documentation (2)

0000-template.mdAdd ADR template with binding-status table+56/-0

Add ADR template with binding-status table

• Introduces a numbered decision record template based on common ADR formats. Includes required sections (Context, Decision, Considered options, Consequences) and adds a dedicated per-binding status table to track convergence across Selenium bindings.

docs/decisions/0000-template.md

---

README.mdDocument ADR scope, workflow, and TLC approval rules+71/-0

Document ADR scope, workflow, and TLC approval rules

• Defines what qualifies for a cross-binding decision record and what does not. Specifies the end-to-end process (propose via PR, discuss in PR/TLC, merge as acceptance/rejection, and binding implementation tracking) plus approval/immutability and numbering rules.

docs/decisions/README.md

---

[qodo-code-review]

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

[titusfortner]

💥 What does this PR do?

Adds docs/decisions/ — a lightweight process for recording design decisions that apply across bindings (API shape, cross-binding semantics, deprecation commitments), plus the template for writing one. Decisions are proposed as PRs, discussed on the PR thread and at TLC meetings, and accepted by TLC consensus; the merged file is the canonical record, so settled questions get answered with a link instead of being re-litigated.

🔧 Implementation Notes

• Format is based on MADR/Nygard ADRs with one Selenium-specific addition: a per-binding status table so convergence across the five bindings is tracked in the record itself.
• These live in trunk rather than the website repo because the audience is contributors and the merge-is-acceptance process depends on the code-review flow. They can be rendered to selenium.dev later without moving the source of truth.

🤖 AI assistance

• AI assisted (complete below)
  • Tool(s): Claude Code
  • What was generated: Initial drafts of the README and template, revised through discussion and review
  • I reviewed all AI output and can explain the change

💡 Additional Considerations

• This PR follows the process it introduces: feedback is encouraged from all contributors; it merges by TLC consensus — a majority of TLC members responding with no unresolved objections, after at least one week open and discussion at a TLC meeting — with the Selenium Project Lead performing the merge. Merging adopts the process.

🔄 Types of changes

• Documentation (contributor process)

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1)📘 Rule violations (0)

1. Filename convention mismatch 🐞 Bug⚙ Maintainability

Description

The ADR template’s supersedence example points to NNNN-title.md, but the README standardizes
decision filenames as NNNN-short-title.md, creating conflicting guidance that can lead to
inconsistent ADR filenames/links when contributors copy the template verbatim.

Code

docs/decisions/0000-template.md[6]

+- Status: Proposed <!-- Proposed | Accepted | Rejected | Superseded by [NNNN](NNNN-title.md) -->

Evidence

The README defines the canonical ADR filename format as NNNN-short-title.md, while the template’s
status-line example uses a different filename (NNNN-title.md), so the two new docs conflict on how
supersedence links should be written.

docs/decisions/README.md[30-32]
docs/decisions/0000-template.md[6-6]
docs/decisions/README.md[65-67]

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 ADR template and README disagree on the expected decision filename pattern for supersedence links (`NNNN-title.md` vs `NNNN-short-title.md`). This can cause inconsistent file naming and incorrect/inconsistent links across ADRs.
## Issue Context
- README instructs authors to create ADRs as `NNNN-short-title.md`.
- Template’s status-line comment suggests `Superseded by [NNNN](NNNN-title.md)`.
## Fix Focus Areas
- docs/decisions/0000-template.md[6-6]
- docs/decisions/README.md[30-32]
- docs/decisions/README.md[65-67]
## Suggested fix
- Update the template’s supersedence example to use `NNNN-short-title.md` (or a neutral placeholder matching the README’s convention).
- Update the README’s `Superseded by [NNNN](...)` example to show the same filename pattern explicitly (e.g., `Superseded by [NNNN](NNNN-short-title.md)`).

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

---

Previous review results

Review updated until commit 9288155

Results up to commit 9554f29

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

1. Filename convention mismatch 🐞 Bug⚙ Maintainability

Description

The ADR template’s supersedence example points to NNNN-title.md, but the README standardizes
decision filenames as NNNN-short-title.md, creating conflicting guidance that can lead to
inconsistent ADR filenames/links when contributors copy the template verbatim.

Code

docs/decisions/0000-template.md[6]

+- Status: Proposed <!-- Proposed | Accepted | Rejected | Superseded by [NNNN](NNNN-title.md) -->

Evidence

The README defines the canonical ADR filename format as NNNN-short-title.md, while the template’s
status-line example uses a different filename (NNNN-title.md), so the two new docs conflict on how
supersedence links should be written.

docs/decisions/README.md[30-32]
docs/decisions/0000-template.md[6-6]
docs/decisions/README.md[65-67]

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 ADR template and README disagree on the expected decision filename pattern for supersedence links (`NNNN-title.md` vs `NNNN-short-title.md`). This can cause inconsistent file naming and incorrect/inconsistent links across ADRs.
## Issue Context
- README instructs authors to create ADRs as `NNNN-short-title.md`.
- Template’s status-line comment suggests `Superseded by [NNNN](NNNN-title.md)`.
## Fix Focus Areas
- docs/decisions/0000-template.md[6-6]
- docs/decisions/README.md[30-32]
- docs/decisions/README.md[65-67]
## Suggested fix
- Update the template’s supersedence example to use `NNNN-short-title.md` (or a neutral placeholder matching the README’s convention).
- Update the README’s `Superseded by [NNNN](...)` example to show the same filename pattern explicitly (e.g., `Superseded by [NNNN](NNNN-short-title.md)`).

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

---

[qodo-code-review]

PR Summary by Qodo

Add ADR process and template under docs/decisions
📝 Documentation🕐 10-20 Minutes

Walkthroughs

Description

• Introduce a Design Decision Record (ADR) log for cross-binding Selenium decisions
• Document proposal/approval workflow (PR discussion + TLC consensus; merge equals acceptance)
• Provide a reusable ADR template including per-binding convergence status tracking

Diagram

flowchart TD
C(["Contributor"]) --> T["Copy template"] --> PR["Open PR (Proposed)"] --> TLC{"TLC consensus"} --> M["Merge PR"] --> ADR["Decision record"] --> B["Update binding status"]
subgraph Legend
direction LR
_term(["Terminator"]) ~~~ _proc["Process"] ~~~ _dec{"Decision"}
end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Host ADRs in selenium.dev (website repo)

• ➕ Immediate public discoverability and site navigation/search integration
• ➕ Keeps governance/process docs near other public-facing documentation
• ➖ Weakens the “merge equals acceptance” workflow tied to core repo reviews
• ➖ Harder to keep contributor-targeted process close to where changes are made

2. Use GitHub Discussions/issues as the canonical decision record

• ➕ Native threading and visibility; easy to reference and participate
• ➕ No need to maintain a file format/template
• ➖ Harder to keep a concise, immutable, durable summary of the final decision
• ➖ More risk of re-litigating settled questions across multiple threads

3. Adopt MADR/Nygard format verbatim (no binding-status table)

• ➕ Maximum familiarity and portability to other ADR tooling
• ➕ Less bespoke structure to maintain
• ➖ Doesn’t directly address Selenium’s multi-binding convergence tracking needs
• ➖ Status per binding would likely drift into external trackers or PR comments

Recommendation: The PR’s approach (ADRs in-repo, merge-as-acceptance, and a per-binding status table) is the best fit for Selenium’s cross-binding governance: it keeps the canonical record in the review workflow contributors already use, while explicitly tracking convergence across languages. The main thing to validate in review is whether the approval/consensus wording matches current TLC expectations.

File Changes

Documentation (2)

0000-template.mdAdd ADR template with binding-status table+56/-0

Add ADR template with binding-status table

• Introduces a numbered decision record template based on common ADR formats. Includes required sections (Context, Decision, Considered options, Consequences) and adds a dedicated per-binding status table to track convergence across Selenium bindings.

docs/decisions/0000-template.md

---

README.mdDocument ADR scope, workflow, and TLC approval rules+71/-0

Document ADR scope, workflow, and TLC approval rules

• Defines what qualifies for a cross-binding decision record and what does not. Specifies the end-to-end process (propose via PR, discuss in PR/TLC, merge as acceptance/rejection, and binding implementation tracking) plus approval/immutability and numbering rules.

docs/decisions/README.md

---

[qodo-code-review]

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

[titusfortner]

💥 What does this PR do?

Adds docs/decisions/ — a lightweight process for recording design decisions that apply across bindings (API shape, cross-binding semantics, deprecation commitments), plus the template for writing one. Decisions are proposed as PRs, discussed on the PR thread and at TLC meetings, and accepted by TLC consensus; the merged file is the canonical record, so settled questions get answered with a link instead of being re-litigated.

🔧 Implementation Notes

• Format is based on MADR/Nygard ADRs with one Selenium-specific addition: a per-binding status table so convergence across the five bindings is tracked in the record itself.
• These live in trunk rather than the website repo because the audience is contributors and the merge-is-acceptance process depends on the code-review flow. They can be rendered to selenium.dev later without moving the source of truth.

🤖 AI assistance

• AI assisted (complete below)
  • Tool(s): Claude Code
  • What was generated: Initial drafts of the README and template, revised through discussion and review
  • I reviewed all AI output and can explain the change

💡 Additional Considerations

• This PR follows the process it introduces: feedback is encouraged from all contributors; it merges by TLC consensus — a majority of TLC members responding with no unresolved objections, after at least one week open and discussion at a TLC meeting — with the Selenium Project Lead performing the merge. Merging adopts the process.

🔄 Types of changes

• Documentation (contributor process)

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1)📘 Rule violations (0)

1. Filename convention mismatch 🐞 Bug⚙ Maintainability

Description

The ADR template’s supersedence example points to NNNN-title.md, but the README standardizes
decision filenames as NNNN-short-title.md, creating conflicting guidance that can lead to
inconsistent ADR filenames/links when contributors copy the template verbatim.

Code

docs/decisions/0000-template.md[6]

+- Status: Proposed <!-- Proposed | Accepted | Rejected | Superseded by [NNNN](NNNN-title.md) -->

Evidence

The README defines the canonical ADR filename format as NNNN-short-title.md, while the template’s
status-line example uses a different filename (NNNN-title.md), so the two new docs conflict on how
supersedence links should be written.

docs/decisions/README.md[30-32]
docs/decisions/0000-template.md[6-6]
docs/decisions/README.md[65-67]

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 ADR template and README disagree on the expected decision filename pattern for supersedence links (`NNNN-title.md` vs `NNNN-short-title.md`). This can cause inconsistent file naming and incorrect/inconsistent links across ADRs.
## Issue Context
- README instructs authors to create ADRs as `NNNN-short-title.md`.
- Template’s status-line comment suggests `Superseded by [NNNN](NNNN-title.md)`.
## Fix Focus Areas
- docs/decisions/0000-template.md[6-6]
- docs/decisions/README.md[30-32]
- docs/decisions/README.md[65-67]
## Suggested fix
- Update the template’s supersedence example to use `NNNN-short-title.md` (or a neutral placeholder matching the README’s convention).
- Update the README’s `Superseded by [NNNN](...)` example to show the same filename pattern explicitly (e.g., `Superseded by [NNNN](NNNN-short-title.md)`).

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

---

Previous review results

Review updated until commit 9288155

Results up to commit 9554f29

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

1. Filename convention mismatch 🐞 Bug⚙ Maintainability

Description

The ADR template’s supersedence example points to NNNN-title.md, but the README standardizes
decision filenames as NNNN-short-title.md, creating conflicting guidance that can lead to
inconsistent ADR filenames/links when contributors copy the template verbatim.

Code

docs/decisions/0000-template.md[6]

+- Status: Proposed <!-- Proposed | Accepted | Rejected | Superseded by [NNNN](NNNN-title.md) -->

Evidence

The README defines the canonical ADR filename format as NNNN-short-title.md, while the template’s
status-line example uses a different filename (NNNN-title.md), so the two new docs conflict on how
supersedence links should be written.

docs/decisions/README.md[30-32]
docs/decisions/0000-template.md[6-6]
docs/decisions/README.md[65-67]

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 ADR template and README disagree on the expected decision filename pattern for supersedence links (`NNNN-title.md` vs `NNNN-short-title.md`). This can cause inconsistent file naming and incorrect/inconsistent links across ADRs.
## Issue Context
- README instructs authors to create ADRs as `NNNN-short-title.md`.
- Template’s status-line comment suggests `Superseded by [NNNN](NNNN-title.md)`.
## Fix Focus Areas
- docs/decisions/0000-template.md[6-6]
- docs/decisions/README.md[30-32]
- docs/decisions/README.md[65-67]
## Suggested fix
- Update the template’s supersedence example to use `NNNN-short-title.md` (or a neutral placeholder matching the README’s convention).
- Update the README’s `Superseded by [NNNN](...)` example to show the same filename pattern explicitly (e.g., `Superseded by [NNNN](NNNN-short-title.md)`).

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

---

[qodo-code-review]

PR Summary by Qodo

Add ADR process and template under docs/decisions
📝 Documentation🕐 10-20 Minutes

Walkthroughs

Description

• Introduce a Design Decision Record (ADR) log for cross-binding Selenium decisions
• Document proposal/approval workflow (PR discussion + TLC consensus; merge equals acceptance)
• Provide a reusable ADR template including per-binding convergence status tracking

Diagram

flowchart TD
C(["Contributor"]) --> T["Copy template"] --> PR["Open PR (Proposed)"] --> TLC{"TLC consensus"} --> M["Merge PR"] --> ADR["Decision record"] --> B["Update binding status"]
subgraph Legend
direction LR
_term(["Terminator"]) ~~~ _proc["Process"] ~~~ _dec{"Decision"}
end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Host ADRs in selenium.dev (website repo)

• ➕ Immediate public discoverability and site navigation/search integration
• ➕ Keeps governance/process docs near other public-facing documentation
• ➖ Weakens the “merge equals acceptance” workflow tied to core repo reviews
• ➖ Harder to keep contributor-targeted process close to where changes are made

2. Use GitHub Discussions/issues as the canonical decision record

• ➕ Native threading and visibility; easy to reference and participate
• ➕ No need to maintain a file format/template
• ➖ Harder to keep a concise, immutable, durable summary of the final decision
• ➖ More risk of re-litigating settled questions across multiple threads

3. Adopt MADR/Nygard format verbatim (no binding-status table)

• ➕ Maximum familiarity and portability to other ADR tooling
• ➕ Less bespoke structure to maintain
• ➖ Doesn’t directly address Selenium’s multi-binding convergence tracking needs
• ➖ Status per binding would likely drift into external trackers or PR comments

Recommendation: The PR’s approach (ADRs in-repo, merge-as-acceptance, and a per-binding status table) is the best fit for Selenium’s cross-binding governance: it keeps the canonical record in the review workflow contributors already use, while explicitly tracking convergence across languages. The main thing to validate in review is whether the approval/consensus wording matches current TLC expectations.

File Changes

Documentation (2)

0000-template.mdAdd ADR template with binding-status table+56/-0

Add ADR template with binding-status table

• Introduces a numbered decision record template based on common ADR formats. Includes required sections (Context, Decision, Considered options, Consequences) and adds a dedicated per-binding status table to track convergence across Selenium bindings.

docs/decisions/0000-template.md

---

README.mdDocument ADR scope, workflow, and TLC approval rules+71/-0

Document ADR scope, workflow, and TLC approval rules

• Defines what qualifies for a cross-binding decision record and what does not. Specifies the end-to-end process (propose via PR, discuss in PR/TLC, merge as acceptance/rejection, and binding implementation tracking) plus approval/immutability and numbering rules.

docs/decisions/README.md

---

[qodo-code-review]

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