Repository navigation
docs: set expectations for AI-assisted contributions - #12492
Timothee Guerin (timotheeguerin) wants to merge 5 commits into
Conversation
|
No changes needing a change description found. |
|
You can try these changes here
|
There was a problem hiding this comment.
🟢 Approval recommended
No active review issues are identified for the documentation updates to AI-assisted contribution expectations and evidence-based review guidance.
No open issues 🎉
What changed in this PR
This documentation-only PR sets expectations for AI-assisted contributions to TypeSpec and aligns code-review guidance with observable evidence rather than assumptions about AI use.
Changes:
- Defines contributor responsibilities for ownership, validation, review engagement, focused changes, and substantive AI disclosure.
- Adds evidence-based review-readiness guidance while reserving decisions to pause review or close contributions for maintainers.
| File | Description |
|---|---|
| CONTRIBUTING.md | Adds AI-assisted contribution expectations and maintainer enforcement guidance. |
| .github/skills/code-review/SKILL.md | Adds contribution-quality and readiness checks grounded in PR descriptions, check results, and review threads. |
Review effort: Balanced
Mark Cowlishaw (markcowl)
left a comment
Mark Cowlishaw (markcowl)
left a comment
There was a problem hiding this comment.
This looks reasonable - personally I think we should abide by these rules as well, in the spirit of practicing what we preach
| - **Validate before requesting review.** Run the relevant builds, tests, lint, and formatting checks locally, including after review-driven changes. Add focused regression tests where appropriate, and investigate CI failures rather than leaving them for reviewers to diagnose. Do not weaken tests or update snapshots merely to make checks pass. State which checks you ran and explain any validation you could not perform. Use a draft PR for work in progress or to ask for help with a blocker. | ||
| - **Engage with review yourself.** Understand the concern behind a comment before changing code. AI may help implement a fix, but you must decide whether it addresses the problem and preserves existing behavior, then review and validate the result. Simply forwarding review comments to an AI tool and submitting its response is not sufficient. The substance of your replies must be your own; translation and grammar assistance are welcome. Ask for clarification or explain your reasoning when you disagree. | ||
| - **Keep changes and communication focused.** Remove unrelated edits, unnecessary abstractions, and redundant tests. Keep descriptions and replies concise, technically accurate, and specific to the contribution. | ||
| - **Disclose substantive AI assistance.** Briefly describe how AI tools were used when they produced substantial portions of the contribution. Routine completion, spelling, grammar, or translation assistance does not require disclosure. |
There was a problem hiding this comment.
We might want to provide an example of what this looks like - we should also be prepared to practice what we preach by following these guidelines. I think a pr assigned to copilot probably needs no other explanation, but prs created through the github app or cli or other tooling should probably have some kind of indication of how AI was used to create the pr.
There was a problem hiding this comment.
at this point I feel like every single pr will have that so might not even be worth it
AI-assisted changes that have not been validated, and review replies that merely relay generated answers, shift the work of understanding and checking contributions onto maintainers.
Set expectations for contributor ownership, appropriate validation, thoughtful review engagement, focused changes, and substantive AI disclosure. Keep the guidelines as the shared source of truth for contributors and code review.
AI assistance was used to research contribution policies and draft the guidelines and review instructions.