[docs] number ADRs by PR and track binding convergence in an issue by titusfortner · Pull Request #17697 · SeleniumHQ/selenium

titusfortner · 2026-06-21T00:10:54Z

🔗 Related Issues

Follow-up to #17665 (design decision record process).

💥 What does this PR do?

Refines the just-merged ADR process based on early experience writing records:

Records are numbered by their PR number instead of an incrementing counter, so the number links straight to the discussion and there is no "next unused number" to coordinate or collide on.
Per-binding convergence moves out of the committed record into a tracking issue. The record keeps only its terminal status (Accepted/Rejected/Superseded), so it stays immutable; the long-lived binding checklist lives in an issue. Adds an "ADR Implementation Tracking" issue form for it.
Clarifies scope so records can group tightly-related sub-choices: independent adoptability alone is not grounds to split a record.
Clarifies altitude so records stay focused on the decision and its rationale (what and why), not the implementation (how).
Adds an ADR pull-request template (.github/PULL_REQUEST_TEMPLATE/adr.md) that points readers at the record and structures the body into related links, proposal notes, discussion, and tracking, documented in the README.
Adds an optional current-behavior table to the record's Context, so per-binding divergence (durable rationale) is captured in the record rather than the forward-looking tracking issue.
Drops the Date field from the template (git already tracks this).

🔧 Implementation Notes

The scope and altitude wording directly answers recurring review feedback on draft ADRs: that records "bundle independently-adoptable decisions" and that they run implementation-heavy.

Tracking lives in a dedicated issue (linked from the record's PR) rather than the PR description, since the PR closes at merge while convergence continues for months.

🤖 AI assistance

AI assisted (complete below)
- Tool(s): Claude Code
- What was generated: README/template edits and the issue form, from a maintainer discussion
- I reviewed all AI output and can explain the change

💡 Additional Considerations

This is a process change to a just-merged TLC decision (#17665), so it should get TLC sign-off rather than a quiet merge.

🔄 Types of changes

Cleanup (formatting, renaming)

qodo-code-review · 2026-06-21T00:11:39Z

PR Summary by Qodo

Number ADRs by PR and move binding convergence to tracking issues
📝 Documentation ⚙️ Configuration changes 🕐 10-20 Minutes

Description

• Switch ADR numbering to use the proposing PR number to avoid coordination and collisions.
• Move per-binding implementation/convergence tracking out of ADR files into a dedicated tracking
 issue.
• Add a GitHub issue form and update ADR docs/template to reflect the new workflow.

Diagram

graph TD
  A["Author drafts ADR"] --> B["Open ADR PR"] --> C["Rename ADR to #NNNN"] --> D{Accepted?} --> E["Open tracking issue"] --> F["Track binding PRs"]
  D --> G["ADR stays immutable\n(status only)"]

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep binding checklist in ADR, but isolate it in a separate section/file

➕ All decision + implementation status stays co-located in git history
➕ No new GitHub process surface area (issue forms)
➖ Encourages frequent churn on an otherwise “immutable” ADR file
➖ Harder to subscribe/triage and link implementing PRs over time than an issue checklist

2. Use GitHub Projects (or a milestone) for per-binding convergence

➕ Richer reporting (filters, status fields, dashboards)
➕ Can track multiple PRs per binding and dependencies
➖ More tooling overhead and inconsistent usage across repos/teams
➖ Less discoverable from the ADR/PR flow than a simple linked issue

3. Automate numbering with a bot (still sequential)

➕ Keeps sequential numbering without human coordination
➕ Can enforce naming/metadata consistency
➖ More maintenance and permissions complexity than PR-numbering
➖ Still doesn’t provide a natural backlink to the discussion like PR numbers do

Recommendation: The PR-number-as-ADR-number approach is the simplest way to guarantee uniqueness and provides a direct link to the discussion without extra tooling. Moving convergence tracking to a dedicated issue is also a good tradeoff: it keeps ADRs stable while giving an update-friendly checklist surface. Projects/milestones can be revisited later if reporting needs outgrow the issue checklist.

Files changed (3) +63 / -26

Documentation (2) +20 / -26

0000-template.mdUpdate ADR template: PR-based numbering and externalize binding tracking +6/-15

Update ADR template: PR-based numbering and externalize binding tracking
• Clarifies that the ADR number (NNNN) is the proposal’s PR number and removes the Date field. Deletes the in-ADR binding status table and replaces it with instructions to use the new tracking issue template after acceptance.
docs/decisions/0000-template.md

README.mdRevise ADR process docs for PR-numbering and tracking issues +14/-11

Revise ADR process docs for PR-numbering and tracking issues

• Updates the process to create ADRs without pre-allocating numbers, then rename using the GitHub-assigned PR number before merge. Replaces the in-record binding-status table guidance with instructions to open and maintain a tracking issue, and updates immutability/numbering rules accordingly.

docs/decisions/README.md

Other (1) +43 / -0

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

Add ADR implementation tracking issue form

• Introduces a GitHub issue form to track per-binding convergence for accepted ADRs. Captures the accepted record/PR reference, a binding checkbox list with implementing PR links, and freeform notes for blockers/caveats.

.github/ISSUE_TEMPLATE/adr-tracking.yml

qodo-code-review · 2026-06-21T00:13:45Z

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 11 rules

1. AI disclosure prompt missing 🐞 Bug ⚙ Maintainability

Description

The ADR pull-request template does not include the AI-assistance disclosure checklist/prompt that
exists in the default PR template, so ADR PRs created with this template won’t be prompted to
include the disclosure that CONTRIBUTING.md requires when substantial AI assistance is used.

Code

.github/PULL_REQUEST_TEMPLATE/adr.md[R17-20]

+### 📌 Tracking
+
+<!-- Filled in on acceptance: open the ADR tracking issue and link it here. -->
+Tracking issue: _(linked on acceptance)_

Evidence

The ADR template currently ends at the Tracking section and contains no AI disclosure prompt. The
repository’s default PR template includes an explicit AI assistance disclosure checklist, and
CONTRIBUTING.md documents the disclosure requirement for substantial AI-assisted contributions.

.github/PULL_REQUEST_TEMPLATE/adr.md[1-20]
.github/PULL_REQUEST_TEMPLATE.md[15-22]
CONTRIBUTING.md[62-73]

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 PR template lacks an AI-assistance disclosure section, unlike the repo’s default PR template. This makes ADR PRs inconsistent with the project’s contribution workflow and reduces the chance authors include the requested disclosure details when AI was used.

## Issue Context
CONTRIBUTING.md asks authors to disclose substantial AI assistance in the PR description (tool name + what was generated). The default PR template includes a dedicated checklist for this, but the ADR-specific template currently ends after the Tracking section.

## Fix Focus Areas
- .github/PULL_REQUEST_TEMPLATE/adr.md[12-20]

Suggested change: add an “🤖 AI assistance” section (copy/align with `.github/PULL_REQUEST_TEMPLATE.md`) after the Tracking section (or before it), so ADR PRs get the same disclosure prompt.

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

2. Missing tracking issue labels 🐞 Bug ⚙ Maintainability

Description

The new ADR tracking issue form does not define default labels, so issues created via it will be
opened unlabeled, unlike existing issue forms that auto-apply triage labels. This makes ADR tracking
issues harder to consistently find/filter in label-based triage workflows.

Code

.github/ISSUE_TEMPLATE/adr-tracking.yml[R1-4]

+name: 📋 ADR Implementation Tracking
+description: Track per-binding convergence on an accepted design decision record (ADR)
+title: "[📋 ADR]: "
+body:

Evidence
The ADR tracking template header includes name/description/title/body but no labels, while the
repo’s other issue templates include labels: [...] for automatic labeling/triage.
.github/ISSUE_TEMPLATE/adr-tracking.yml[1-4]
.github/ISSUE_TEMPLATE/feature_proposal.yml[1-5]
.github/ISSUE_TEMPLATE/bug-report.yml[1-5]

Agent prompt

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

## Issue description
The new ADR tracking issue template (`.github/ISSUE_TEMPLATE/adr-tracking.yml`) is missing a `labels:` field, so newly created tracking issues will be created without any labels.

## Issue Context
Other issue forms in `.github/ISSUE_TEMPLATE/` define default labels (notably `A-needs-triaging`), which suggests the repo relies on labels for consistent routing/filtering.

## Fix Focus Areas
- .github/ISSUE_TEMPLATE/adr-tracking.yml[1-6]

## Suggested change
Add a `labels:` entry near the top of the template (after `title:` is consistent with other templates), using an existing label such as `A-needs-triaging` (and any additional labels the maintainers want for ADR tracking).

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

3. ~~Issue template link wrong~~ ✓ Resolved 🐞 Bug ≡ Correctness

Description

docs/decisions/README.md tells users to open an ADR tracking issue using the template, but the link
points to the template YAML file in the repo (it won’t launch the pre-filled new-issue form). Since
blank issues are disabled, this can leave users unsure how to create the tracking issue correctly.

Code

docs/decisions/README.md[R44-46]

+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

Evidence
The README’s link target is a repository file path, not an issue-creation URL; and the repo’s issue
template configuration disables blank issues, making the intended flow template-driven.
docs/decisions/README.md[44-48]
.github/ISSUE_TEMPLATE/config.yml[1-2]
.github/ISSUE_TEMPLATE/adr-tracking.yml[1-4]

Agent prompt

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

### Issue description
`docs/decisions/README.md` instructs users to use the **ADR Implementation Tracking** issue template, but the current markdown link targets the template YAML file in `.github/ISSUE_TEMPLATE/`, which only shows the file contents and does not open the GitHub issue creation form.

### Issue Context
This repo disables blank issues, so users are expected to create issues via templates.

### Fix Focus Areas
- docs/decisions/README.md[44-48]

### Suggested fix
Update the link to point to the GitHub issue creation URL for the template, e.g.:
- `https://github.com/SeleniumHQ/selenium/issues/new?template=adr-tracking.yml`

Optionally include a short instruction like “click **New issue** and choose *ADR Implementation Tracking*” if you prefer not to hardcode the full URL.

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

4. ~~ADR filename steps unclear~~ ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

The new ADR PR template shows the record as docs/decisions/NNNN-short-title.md, but the documented
process creates short-title.md first and renames to NNNN-short-title.md only after the PR number
exists. This mismatch can confuse authors using the template about the expected initial
filename/rename sequence.

Code

.github/PULL_REQUEST_TEMPLATE/adr.md[R6-9]

+Proposes ADR: **_short title_**
+
+- Record: `docs/decisions/NNNN-short-title.md` <!-- rename to this PR's number before merge -->
+

Evidence

The PR template instructs a numbered filename (NNNN-short-title.md) while the README process
explicitly starts with an unnumbered short-title.md and renames after GitHub assigns the PR
number.

.github/PULL_REQUEST_TEMPLATE/adr.md[6-9]
docs/decisions/README.md[42-45]

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 PR template currently presents only the final, numbered ADR filename, while the documented process expects authors to start with an unnumbered filename and rename after the PR number is assigned.

## Issue Context
This is contributor-facing guidance. Aligning the PR template with the README process reduces confusion and avoids back-and-forth during PR creation.

## Fix Focus Areas
- .github/PULL_REQUEST_TEMPLATE/adr.md[6-9]

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

Previous review results

Review updated until commit 532550c

Results up to commit 68cbfff

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

1. ~~Issue template link wrong~~ ✓ Resolved 🐞 Bug ≡ Correctness

Description

docs/decisions/README.md tells users to open an ADR tracking issue using the template, but the link
points to the template YAML file in the repo (it won’t launch the pre-filled new-issue form). Since
blank issues are disabled, this can leave users unsure how to create the tracking issue correctly.

Code

docs/decisions/README.md[R44-46]

+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

Evidence
The README’s link target is a repository file path, not an issue-creation URL; and the repo’s issue
template configuration disables blank issues, making the intended flow template-driven.
docs/decisions/README.md[44-48]
.github/ISSUE_TEMPLATE/config.yml[1-2]
.github/ISSUE_TEMPLATE/adr-tracking.yml[1-4]

Agent prompt

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

### Issue description
`docs/decisions/README.md` instructs users to use the **ADR Implementation Tracking** issue template, but the current markdown link targets the template YAML file in `.github/ISSUE_TEMPLATE/`, which only shows the file contents and does not open the GitHub issue creation form.

### Issue Context
This repo disables blank issues, so users are expected to create issues via templates.

### Fix Focus Areas
- docs/decisions/README.md[44-48]

### Suggested fix
Update the link to point to the GitHub issue creation URL for the template, e.g.:
- `https://github.com/SeleniumHQ/selenium/issues/new?template=adr-tracking.yml`

Optionally include a short instruction like “click **New issue** and choose *ADR Implementation Tracking*” if you prefer not to hardcode the full URL.

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

Results up to commit 533e2fb

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

1. ~~ADR filename steps unclear~~ ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

The new ADR PR template shows the record as docs/decisions/NNNN-short-title.md, but the documented
process creates short-title.md first and renames to NNNN-short-title.md only after the PR number
exists. This mismatch can confuse authors using the template about the expected initial
filename/rename sequence.

Code

.github/PULL_REQUEST_TEMPLATE/adr.md[R6-9]

+Proposes ADR: **_short title_**
+
+- Record: `docs/decisions/NNNN-short-title.md` <!-- rename to this PR's number before merge -->
+

Evidence

The PR template instructs a numbered filename (NNNN-short-title.md) while the README process
explicitly starts with an unnumbered short-title.md and renames after GitHub assigns the PR
number.

.github/PULL_REQUEST_TEMPLATE/adr.md[6-9]
docs/decisions/README.md[42-45]

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 PR template currently presents only the final, numbered ADR filename, while the documented process expects authors to start with an unnumbered filename and rename after the PR number is assigned.

## Issue Context
This is contributor-facing guidance. Aligning the PR template with the README process reduces confusion and avoids back-and-forth during PR creation.

## Fix Focus Areas
- .github/PULL_REQUEST_TEMPLATE/adr.md[6-9]

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

Results up to commit 18c53ab

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

1. Missing tracking issue labels 🐞 Bug ⚙ Maintainability

Description

The new ADR tracking issue form does not define default labels, so issues created via it will be
opened unlabeled, unlike existing issue forms that auto-apply triage labels. This makes ADR tracking
issues harder to consistently find/filter in label-based triage workflows.

Code

.github/ISSUE_TEMPLATE/adr-tracking.yml[R1-4]

+name: 📋 ADR Implementation Tracking
+description: Track per-binding convergence on an accepted design decision record (ADR)
+title: "[📋 ADR]: "
+body:

Evidence
The ADR tracking template header includes name/description/title/body but no labels, while the
repo’s other issue templates include labels: [...] for automatic labeling/triage.
.github/ISSUE_TEMPLATE/adr-tracking.yml[1-4]
.github/ISSUE_TEMPLATE/feature_proposal.yml[1-5]
.github/ISSUE_TEMPLATE/bug-report.yml[1-5]

Agent prompt

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

## Issue description
The new ADR tracking issue template (`.github/ISSUE_TEMPLATE/adr-tracking.yml`) is missing a `labels:` field, so newly created tracking issues will be created without any labels.

## Issue Context
Other issue forms in `.github/ISSUE_TEMPLATE/` define default labels (notably `A-needs-triaging`), which suggests the repo relies on labels for consistent routing/filtering.

## Fix Focus Areas
- .github/ISSUE_TEMPLATE/adr-tracking.yml[1-6]

## Suggested change
Add a `labels:` entry near the top of the template (after `title:` is consistent with other templates), using an existing label such as `A-needs-triaging` (and any additional labels the maintainers want for ADR tracking).

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

Results up to commit 3754bd8

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

1. AI disclosure prompt missing 🐞 Bug ⚙ Maintainability

Description

The ADR pull-request template does not include the AI-assistance disclosure checklist/prompt that
exists in the default PR template, so ADR PRs created with this template won’t be prompted to
include the disclosure that CONTRIBUTING.md requires when substantial AI assistance is used.

Code

.github/PULL_REQUEST_TEMPLATE/adr.md[R17-20]

+### 📌 Tracking
+
+<!-- Filled in on acceptance: open the ADR tracking issue and link it here. -->
+Tracking issue: _(linked on acceptance)_

Evidence

The ADR template currently ends at the Tracking section and contains no AI disclosure prompt. The
repository’s default PR template includes an explicit AI assistance disclosure checklist, and
CONTRIBUTING.md documents the disclosure requirement for substantial AI-assisted contributions.

.github/PULL_REQUEST_TEMPLATE/adr.md[1-20]
.github/PULL_REQUEST_TEMPLATE.md[15-22]
CONTRIBUTING.md[62-73]

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 PR template lacks an AI-assistance disclosure section, unlike the repo’s default PR template. This makes ADR PRs inconsistent with the project’s contribution workflow and reduces the chance authors include the requested disclosure details when AI was used.

## Issue Context
CONTRIBUTING.md asks authors to disclose substantial AI assistance in the PR description (tool name + what was generated). The default PR template includes a dedicated checklist for this, but the ADR-specific template currently ends after the Tracking section.

## Fix Focus Areas
- .github/PULL_REQUEST_TEMPLATE/adr.md[12-20]

Suggested change: add an “🤖 AI assistance” section (copy/align with `.github/PULL_REQUEST_TEMPLATE.md`) after the Tracking section (or before it), so ADR PRs get the same disclosure prompt.

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

…implementation

qodo-code-review · 2026-06-21T18:08:48Z

Code review by qodo was updated up to the latest commit 1f202c3

qodo-code-review · 2026-06-21T19:33:00Z

Code review by qodo was updated up to the latest commit 533e2fb

qodo-code-review · 2026-06-21T19:48:33Z

Code review by qodo was updated up to the latest commit 18c53ab

…scussion

qodo-code-review · 2026-06-21T20:53:42Z

Code review by qodo was updated up to the latest commit 3754bd8

qodo-code-review · 2026-06-21T21:30:58Z

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

qodo-code-review · 2026-06-21T22:17:38Z

Code review by qodo was updated up to the latest commit 532550c

[docs] number ADRs by PR and track binding convergence in an issue

68cbfff

titusfortner added the A-needs decision TLC needs to discuss and agree label Jun 21, 2026

selenium-ci added the B-build Includes scripting, bazel and CI integrations label Jun 21, 2026

titusfortner added 2 commits June 21, 2026 07:35

[docs] link ADR tracking to the new-issue form, not the template source

8e7cae9

[docs] clarify ADR scope: group related choices, keep records out of …

1f202c3

…implementation

titusfortner added 2 commits June 21, 2026 14:30

[docs] add ADR pull-request template and document its use

765981f

[docs] add optional current-behavior table to ADR Context

533e2fb

[docs] drop AI-assistance section from ADR PR template

18c53ab

[docs] ground ADR PR template in real usage: related links and TLC di…

3754bd8

…scussion

titusfortner added 2 commits June 21, 2026 16:21

[docs] move ADR PR template guidance into a comment

e73163a

[docs] add reader-facing intro and proposal notes to ADR PR template

cfc4db1

[docs] reorder ADR PR template; frame contention as discussion questions

532550c

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[docs] number ADRs by PR and track binding convergence in an issue#17697

[docs] number ADRs by PR and track binding convergence in an issue#17697
titusfortner wants to merge 10 commits into
trunkfrom
adr_template

titusfortner commented Jun 21, 2026 •

edited

Loading

Uh oh!

qodo-code-review Bot commented Jun 21, 2026

Uh oh!

qodo-code-review Bot commented Jun 21, 2026 •

edited

Loading

Uh oh!

qodo-code-review Bot commented Jun 21, 2026

Uh oh!

qodo-code-review Bot commented Jun 21, 2026

Uh oh!

qodo-code-review Bot commented Jun 21, 2026

Uh oh!

qodo-code-review Bot commented Jun 21, 2026

Uh oh!

qodo-code-review Bot commented Jun 21, 2026

Uh oh!

qodo-code-review Bot commented Jun 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

titusfortner commented Jun 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔗 Related Issues

💥 What does this PR do?

🔧 Implementation Notes

🤖 AI assistance

💡 Additional Considerations

🔄 Types of changes

Uh oh!

qodo-code-review Bot commented Jun 21, 2026

PR Summary by Qodo

Uh oh!

qodo-code-review Bot commented Jun 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review by Qodo

Previous review results

Uh oh!

qodo-code-review Bot commented Jun 21, 2026

Uh oh!

qodo-code-review Bot commented Jun 21, 2026

Uh oh!

qodo-code-review Bot commented Jun 21, 2026

Uh oh!

qodo-code-review Bot commented Jun 21, 2026

Uh oh!

qodo-code-review Bot commented Jun 21, 2026

Uh oh!

qodo-code-review Bot commented Jun 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

titusfortner commented Jun 21, 2026 •

edited

Loading

qodo-code-review Bot commented Jun 21, 2026 •

edited

Loading