Skip to content

Add AI-assisted contribution guidance and strengthen verification expectations - #11190

Draft
niels9001 wants to merge 2 commits into
microsoft:mainfrom
niels9001:niels9001-contributing-guide-review
Draft

Add AI-assisted contribution guidance and strengthen verification expectations#11190
niels9001 wants to merge 2 commits into
microsoft:mainfrom
niels9001:niels9001-contributing-guide-review

Conversation

@niels9001

@niels9001 niels9001 commented Jun 23, 2026

Copy link
Copy Markdown
Collaborator

Fixes

N/A - documentation/process improvement, no tracking issue.

PR Type

  • Bugfix
  • Feature
  • Code style update (formatting, renaming)
  • Refactoring (no functional changes, no API changes)
  • Build related changes
  • Documentation content changes
  • Other (please describe):

Description

WinUI's contributor docs had no guidance for AI/agent-assisted contributions, which are increasingly common and, when unmanaged, flood maintainers with low-context or duplicate PRs. Other major Microsoft repos (notably microsoft/TypeScript and microsoft/typescript-go) have addressed this with explicit policies; WinUI had a gap. This PR closes that gap, reinforces that authors must verify their own changes, and adds a maintainer command to request that verification.

Current Behavior

  • No policy on AI-assisted or autonomous-agent PRs, and no disclosure mechanism.
  • No root AGENTS.md to orient coding agents to the repo's contribution rules.
  • Two divergent contribution-handling docs: CONTRIBUTION_HANDLING.md at the root (orphaned, nothing links to it) and the canonical docs/external/contribution_handling.md that CONTRIBUTING.md and README.md link to.
  • No quick way for maintainers to ask a contributor to manually verify their change.

New Behavior

  • CONTRIBUTING.md: new "Use of AI assistance" section (AI tools are welcome, disclosure is required, bulk/agent-driven PRs are not accepted, plus an "Instructions for autonomous coding agents" subsection). New "Verify your own changes" subsection requiring repro/verification steps and a screenshot or short screen recording for user-visible changes. Heading renamed to "Contributing to WinUI".
  • .github/PULL_REQUEST_TEMPLATE.md: adds AI disclosure checkboxes, a verification / repro steps field, a "ran and verified the new behavior myself" checkbox, and a "Screenshots / Screen recording" section.
  • New root AGENTS.md: agent-facing orientation covering PR acceptance rules, the proposal gate for public API/UI, manual verification expectations, build/test skills, and PR requirements.
  • New .github/workflows/needs-verification-command.yml: a maintainer can comment /needs-verification on an issue or PR to post a templated request asking the author to manually verify their change (linking to the "Verify your own changes" section) and apply the existing needs-author-feedback label, which plugs into the repo's stale-bot automation. The message is intentionally neutral and does not call out AI.
  • Removes the orphaned root CONTRIBUTION_HANDLING.md; the canonical copy at docs/external/contribution_handling.md remains.

The AI policy language is adapted from the TypeScript repos but tailored to WinUI's process (2 approvals, CLA, feature-proposal gate, squash merge).

Customer Impact

Contributor-facing process/docs plus one maintainer-only automation. No product or runtime code changes. Sets clearer expectations for community contributors and reduces maintainer triage burden.

Regression Potential

  • Low risk — isolated change, limited scope
  • Medium risk — touches shared components or public APIs
  • High risk — architectural or breaking API change

Docs/templates plus a new comment-triggered workflow that is gated to maintainers (OWNER/MEMBER/COLLABORATOR) and reuses an existing label. Verified internal links resolve, no remaining references point to the removed file, and the workflow YAML parses.

How Has This Been Tested?

Verification / repro steps:

  1. Confirmed grep finds no remaining references to CONTRIBUTION_HANDLING.md; CONTRIBUTING.md and README.md still link to docs/external/contribution_handling.md.
  2. Verified the "Use of AI assistance" and "Verify your own changes" anchors match the header/command links.
  3. Validated needs-verification-command.yml parses as YAML and gates on the command + maintainer association; it reuses the needs-author-feedback label already used by .github/policies/resourceManagement.yml.
  • I have performed a self-review of my own code
  • I have run and verified the new behavior myself (not just relied on tools or AI output)
  • I have added tests to cover my changes
  • Existing tests pass locally

AI Assistance

  • AI coding tools (e.g. Copilot, Claude, Codex, Cursor) were used to author part or all of this change
  • I have read and understand every change in this PR, have verified it works, and can discuss and revise it in review

Screenshots / Screen recording

N/A - text and workflow change.

…ectations

Adds an explicit policy for AI/agent-assisted contributions, modeled on the
TypeScript and typescript-go repos, and reinforces author verification of changes.

- CONTRIBUTING.md: new 'Use of AI assistance' section (disclosure requirement,
  bulk/agent-driven PR ban, instructions for autonomous agents) plus a 'Verify
  your own changes' subsection covering repro steps and screenshots/recordings.
  Rename heading to 'Contributing to WinUI'.
- PULL_REQUEST_TEMPLATE.md: add AI disclosure checkboxes, a verification/repro
  steps field, a 'verified the new behavior myself' checkbox, and a
  Screenshots / Screen recording section.
- AGENTS.md: new root file orienting coding agents to contribution rules,
  manual verification expectations, build/test skills, and PR requirements.
- Remove orphaned root CONTRIBUTION_HANDLING.md (canonical copy lives at
  docs/external/contribution_handling.md).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@microsoft-github-policy-service microsoft-github-policy-service Bot added the needs-triage Issue needs to be triaged by the area owners label Jun 23, 2026
Comment-triggered workflow: a maintainer commenting /needs-verification on an issue or PR posts a templated request asking the author to manually verify their change (linking to the 'Verify your own changes' section of CONTRIBUTING.md) and applies the existing needs-author-feedback label, which plugs into the repo's stale-bot automation.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs-triage Issue needs to be triaged by the area owners

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant