[docs] add design decision record process and template#17665
[docs] add design decision record process and template#17665titusfortner wants to merge 1 commit into
Conversation
Code Review by Qodo
1. Filename convention mismatch
|
PR Summary by QodoAdd ADR process and template under docs/decisions WalkthroughsDescription• 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 Diagramflowchart 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
High-Level AssessmentThe following are alternative approaches to this PR: 1. Host ADRs in selenium.dev (website repo)
2. Use GitHub Discussions/issues as the canonical decision record
3. Adopt MADR/Nygard format verbatim (no binding-status table)
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 ChangesDocumentation (2)
|
| what would resolve it. | ||
| - Records are accepted by consensus: a majority of TLC members have responded, none with | ||
| an unresolved objection. Before acceptance, a record must have been open at least one | ||
| week and an agenda item at a TLC meeting — no one should learn of a decision after it |
There was a problem hiding this comment.
We need to have a process where minutes are created during the discussion in the TLC meeting . These need to be fairly verbose minutes rather than yes/no so that clear objections and reasonings are mentioned
There was a problem hiding this comment.
Agree we should have better minutes. We used to do this better.
Voting and objections should be recorded on GitHub PR, not verbally in meeting?
| `Rejected`; proposals withdrawn or abandoned before TLC consideration are closed and the | ||
| number lapses. | ||
| 4. **Implement.** Each binding tracks its convergence in the decision's binding-status table. | ||
| Updating that table (and only that table) doesn't require TLC review. |
There was a problem hiding this comment.
We need to have a high level issue created with sub tasks per binding so we can meaningfully track implementation status. We should also make sure that PRs eventually have docs links
There was a problem hiding this comment.
Do we need separate issue, or can we track it against the ADR itself?
|
Code review by qodo was updated up to the latest commit 9288155 |
3 participants
💥 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
🤖 AI assistance
💡 Additional Considerations
🔄 Types of changes