From be4704550475b01775ad1927c662daf8aadcb978 Mon Sep 17 00:00:00 2001 From: Cody Barnes Date: Thu, 4 Jun 2026 22:08:25 -0700 Subject: [PATCH] Improve AI and contribution documentation governance Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/PULL_REQUEST_TEMPLATE.md | 73 +++++++++++- Agents.md | 112 +++++++++++++++++++ CONTRIBUTING.md | 42 +++++++ README.md | 5 + docs/adr/README.md | 28 +++++ documents/crosswalk/webrtcnet-api-to-spec.md | 5 + documents/specs/index/README.md | 19 +++- 7 files changed, 276 insertions(+), 8 deletions(-) create mode 100644 Agents.md create mode 100644 CONTRIBUTING.md create mode 100644 docs/adr/README.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 775c918..b2ab1d5 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -2,11 +2,72 @@ Describe the change and its motivation. -## Checklist +## Change Area (required) + +- [ ] API-only managed change (`WebRtcNet.Api` / managed-only behavior) +- [ ] Interop / marshaling / native-boundary change +- [ ] Docs/infra only (no behavior change) + +## Required Evidence (for behavioral/API changes) + +If this change affects WebRTC or Media Capture behavior, complete all sections below. +If not applicable, write `N/A - no behavioral change`. + +### 1) W3C reference (required when applicable) + +- Spec section link(s): +- Relevant requirement quote(s): + +### 2) Google source reference (required when applicable) + +Provide pinned references: path + revision context (commit SHA or branch/tag). + +- Source path(s): +- Revision context (SHA/branch/tag): +- Notes on alignment: + +### 3) Intended observable behavior (required when applicable) + +Describe externally observable behavior (state transitions, event ordering, timing, errors). + +- Behavior summary: +- Why this behavior is correct: + +### 4) Divergence from Google reference (required if diverging) + +- [ ] No divergence +- [ ] Divergence exists (explain below) +- Divergence details (what differs, why .NET/runtime needs require it, and which web-observable semantics are preserved): + +## Test Evidence (required) + +### Tests added/updated + +- + +### Commands run + results + +- + +### Change-area test gate confirmation + +- [ ] API-only managed change: ran managed NUnit tests +- [ ] Interop/native-boundary change: ran interop unit tests (when environment available) +- [ ] Required environment unavailable (explain below) + +### If environment unavailable (required when checked above) + +- Missing environment/dependency: +- What was run instead: +- Residual risk: + +## Documentation -- [ ] I ran relevant build/tests for changed code. - [ ] I updated documentation for externally visible behavior changes. -- [ ] If this PR changes W3C-aligned API behavior (`WebRtcNet.Api`), I reviewed: - - `documents\crosswalk\webrtcnet-api-to-spec.md` - - `documents\specs\index\spec-map.md` - - Local spec snapshots (refreshed via `.\scripts\update-spec-docs.ps1` when needed) +- [ ] No external docs impact. + +## Spec/Crosswalk Review (required for W3C-aligned behavior changes) + +- [ ] Reviewed `documents\crosswalk\webrtcnet-api-to-spec.md` +- [ ] Reviewed `documents\specs\index\spec-map.md` +- [ ] Refreshed/checked local spec snapshots (`.\scripts\update-spec-docs.ps1`) when needed diff --git a/Agents.md b/Agents.md new file mode 100644 index 0000000..6524d3e --- /dev/null +++ b/Agents.md @@ -0,0 +1,112 @@ + +## 1. Think Before Coding + +**Don't assume. Don't hide confusion. Surface tradeoffs.** + +Before implementing: +- State your assumptions explicitly. If uncertain, ask. +- If multiple interpretations exist, present them - don't pick silently. +- If a simpler approach exists, say so. Push back when warranted. +- If something is unclear, stop. Name what's confusing. Ask. + +## 2. Simplicity First + +**Minimum code that solves the problem. Nothing speculative.** + +- No features beyond what was asked. +- No abstractions for single-use code. +- No "flexibility" or "configurability" that wasn't requested. +- No error handling for impossible scenarios. +- If you write 200 lines and it could be 50, rewrite it. + +Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify. + +## 3. Surgical Changes + +**Touch only what you must. Clean up only your own mess.** + +When editing existing code: +- Don't "improve" adjacent code, comments, or formatting. +- Don't refactor things that aren't broken. +- Match existing style, even if you'd do it differently. +- If you notice unrelated dead code, mention it - don't delete it. + +When your changes create orphans: +- Remove imports/variables/functions that YOUR changes made unused. +- Don't remove pre-existing dead code unless asked, but do surface these orphans to me. + +The test: Every changed line should trace directly to the user's request. + +## 4. Goal-Driven Execution + +**Define success criteria. Loop until verified.** + +Transform tasks into verifiable goals: +- "Add validation" → "Write tests for invalid inputs, then make them pass" +- "Fix the bug" → "Write a test that reproduces it, then make it pass" +- "Refactor X" → "Ensure tests pass before and after" + +For multi-step tasks, state a brief plan: +``` +1. [Step] → verify: [check] +2. [Step] → verify: [check] +3. [Step] → verify: [check] +``` + +Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. + +## 5. Standards and Source Alignment (AI-Specific) + +### 5.0 Instruction precedence and scope + +- If guidance conflicts, apply this order: + 1. higher-level runtime/system constraints + 2. this `Agents.md` + 3. path- or tool-specific guidance + 4. ad hoc workflow suggestions +- `Agents.md` defines AI execution behavior and guardrails. +- Human contributor workflow requirements live in `CONTRIBUTING.md`. + +### 5.1 Authority and implementation order + +- **MUST** treat W3C specs as normative intent for behavior and semantics. +- **MUST** treat Google implementations as the primary implementation reference. +- **MUST** use this lookup order when implementing behavior: + 1. `libwebrtc` API/implementation + 2. Blink bindings/behavior glue + 3. Chromium tests and call sites +- **MAY** adapt for .NET/runtime constraints, but adaptations **MUST** be minimal and **MUST NOT** change required observable behavior unless explicitly documented. + +### 5.2 Web-compatibility obligations + +- Changes **MUST** preserve web-expected behavior across: + - state machine transitions + - promise/task resolution timing + - event ordering + - error taxonomy +- If exact parity is not feasible, the deviation **MUST** be explicit and justified. + +### 5.3 .NET API mapping rules + +- Public .NET APIs **MUST** use standard .NET naming/casing. +- XML docs **MUST** map terms back to relevant W3C concepts when names differ. +- Promise-style APIs **MUST** map to `Task`/`ValueTask`. +- Event callbacks **MUST** map to .NET events with `EventArgs`. +- `CancellationToken` **SHOULD** be used where cancellation/timeout semantics apply. +- Legacy callback-style `navigator.getUserMedia(...)` support is **OUT OF SCOPE**. + +### 5.4 Media Capture scope for this project + +- Media Capture scope and priority policy are defined in `CONTRIBUTING.md`. + +### 5.5 Divergence, failures, and traceability + +- When diverging from Google reference behavior, changes **MUST** include: + - upstream Google reference (path + revision context) + - what differs + - why .NET/runtime needs require it + - which web-observable semantics are preserved + - test evidence for preserved behavior +- Implementations **MUST NOT** use silent no-ops or success-shaped stubs for unsupported features. +- Unsupported features **MUST** fail explicitly. +- Keep concise source intent hints in code/XML docs; keep fuller rationale in PR/issue documentation. \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f8e33fe --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,42 @@ +# Contributing to WebRtcNet + +This document defines contributor workflow requirements for this repository. + +## 1. Behavioral alignment requirements + +When a change affects WebRTC or Media Capture behavior, contributors **MUST**: + +1. Reference the relevant W3C requirement(s). +2. Reference upstream Google implementation behavior. +3. Demonstrate expected observable behavior in tests. + +Upstream references **MUST** be pinned to a revision in PR/issue notes (path + commit/branch context) so behavior can be re-validated later. + +## 2. Required PR evidence block + +PR descriptions for behavioral changes **MUST** include: + +1. **W3C reference**: section link(s) +2. **Google source reference**: libwebrtc/Blink/Chromium path(s) and revision context +3. **Behavior summary**: what observable behavior is intended and why +4. **Test evidence**: tests added/updated and what they prove + +For `WebRtcNet.Api` behavior changes, PRs **MUST** also update or validate: + +- `documents\specs\index\spec-map.json` (canonical API symbol to spec anchor map) +- `documents\specs\index\spec-map.md` (human-readable mirror) +- `documents\crosswalk\webrtcnet-api-to-spec.md` (implementation status/adaptation notes) + +## 3. Test gates by change area + +- API-only managed changes **MUST** run managed NUnit tests. +- Interop/marshaling/native-boundary changes **MUST** also run interop unit tests when environment support is available. +- If a required environment is unavailable, PRs **MUST** explicitly call that out and identify what was run instead. + +## 4. Scope priorities for Media Capture + +- Prioritize WebRTC-critical Media Capture functionality first. +- `P0`: `getUserMedia`, track lifecycle/events, and constraints needed for call setup quality. +- `P1`: device enumeration/change and high-value constraints/settings (including `backgroundBlur`). +- Legacy callback `navigator.getUserMedia(success, error)` is out of scope. +- Extended constraints beyond immediate needs are in near-term scope and should be added incrementally. diff --git a/README.md b/README.md index 2b64834..4028b6f 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,11 @@ WebRtcNet currently uses WebRTC branch-heads/7778, which corresponds to Chromium See [WebRTC 1.0: Real-time Communication Between Browsers](https://www.w3.org/TR/webrtc/) for API documentation. +## Contribution and AI guidance + +- Human contributor workflow requirements: `CONTRIBUTING.md` +- AI execution guardrails for this repository: `Agents.md` + ## Local W3C spec corpus This repository keeps a local standards corpus in `documents\specs\` to support standards-alignment work in `WebRtcNet.Api` without repeated web fetching. diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 0000000..03bf4a0 --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,28 @@ +# Architecture Decision Records (ADRs) + +This folder stores architectural decisions that affect implementation direction, constraints, and tradeoffs. + +## ADR index + +| ADR | Title | Status | +| --- | --- | --- | +| [0001](0001-host-entry-point-for-api-access.md) | Host entry point for API access | accepted | +| [0002](0002-caller-callee-tcp-alignment.md) | Caller/Callee TCP alignment | accepted | + +## ADR format (required) + +Each new ADR should include these sections: + +1. Status +2. Date +3. Context +4. Decision +5. Consequences +6. Alternatives considered +7. References (issues/PRs/spec sections/code paths) + +## Guidance + +- Keep ADRs concise and decision-focused. +- Link affected code paths and related tests when possible. +- Supersede prior ADRs explicitly rather than silently changing direction. diff --git a/documents/crosswalk/webrtcnet-api-to-spec.md b/documents/crosswalk/webrtcnet-api-to-spec.md index 22862b3..37858c5 100644 --- a/documents/crosswalk/webrtcnet-api-to-spec.md +++ b/documents/crosswalk/webrtcnet-api-to-spec.md @@ -4,6 +4,11 @@ Status: seeded This crosswalk maps high-value `WebRtcNet.Api` symbols to current W3C specification anchors and records expected adaptation notes for .NET usage. +Source-of-truth note: + +- `documents\specs\index\spec-map.json` is the canonical API symbol to spec anchor map. +- This crosswalk adds implementation status, adaptation notes, and priority guidance. + ## WebRTC 1.0 | API Symbol | Spec Section | Anchor URL | Status | Adaptation Notes | diff --git a/documents/specs/index/README.md b/documents/specs/index/README.md index b5f0790..ab67dc6 100644 --- a/documents/specs/index/README.md +++ b/documents/specs/index/README.md @@ -2,8 +2,23 @@ This folder contains cross-spec metadata. -Planned files: +Canonical files: - `spec-map.json`: Machine-readable map from API symbols to spec anchors. -- `spec-map.md`: Human-readable map. +- `spec-map.md`: Human-readable map (derived from `spec-map.json`). - `update-log.md`: Refresh history and source metadata. + +## Source-of-truth policy + +- `spec-map.json` is the source of truth for API symbol to W3C anchor mapping. +- `spec-map.md` should be kept in sync with `spec-map.json`. +- `documents\crosswalk\webrtcnet-api-to-spec.md` captures implementation status and adaptation notes. + +## Status vocabulary + +Use one of the following values for mapping and implementation status: + +- `seeded` +- `partial` +- `implemented` +- `todo`