From f045bc2d4915c226a67cf701780db3dbc5834d96 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Wed, 4 Nov 2026 10:33:25 -0500 Subject: [PATCH 1/5] docs: set expectations for AI-assisted contributions --- CONTRIBUTING.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c096fd166a6..fa5d4d1b5c7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -355,6 +355,20 @@ See existing release notes for examples. # Pull request +## AI-assisted contributions + +We welcome contributions developed with AI assistance. These tools do not replace your judgment or change our expectations for contribution quality. The following applies to code, tests, documentation, issues, and review discussions. + +- **Own and understand your contribution.** Review every change before submitting it. Understand the surrounding code and be prepared to explain why your approach is correct in your own words. You remain responsible for the correctness, maintainability, and licensing of everything you submit. +- **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. + +Maintainers may pause review or close contributions that are unvalidated, cannot be explained by their author, or repeatedly fail to engage meaningfully with feedback. These expectations apply regardless of the tools used. + +These guidelines are inspired by the policies of [Astropy](https://github.com/astropy/astropy-project/blob/main/policies/ai-policy.md), [Home Assistant](https://contributors.home-assistant.io/start/ai-policy/), and [Apache Airflow](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#gen-ai-assisted-contributions). + ## Trigger TypeSpec Playground Try It build For contributors of the repo the build will trigger automatically but for other's forks it will need a manual trigger from a contributor. From aac7b42e2880f2aae2c971daa1195649ca26e204 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Wed, 4 Nov 2026 10:35:14 -0500 Subject: [PATCH 2/5] docs: remove contribution-policy inspiration references --- CONTRIBUTING.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fa5d4d1b5c7..c076868ad95 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -367,8 +367,6 @@ We welcome contributions developed with AI assistance. These tools do not replac Maintainers may pause review or close contributions that are unvalidated, cannot be explained by their author, or repeatedly fail to engage meaningfully with feedback. These expectations apply regardless of the tools used. -These guidelines are inspired by the policies of [Astropy](https://github.com/astropy/astropy-project/blob/main/policies/ai-policy.md), [Home Assistant](https://contributors.home-assistant.io/start/ai-policy/), and [Apache Airflow](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#gen-ai-assisted-contributions). - ## Trigger TypeSpec Playground Try It build For contributors of the repo the build will trigger automatically but for other's forks it will need a manual trigger from a contributor. From 858d49fe53516cff5b90fae0746df3a0ce7e8c07 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Wed, 4 Nov 2026 11:09:32 -0500 Subject: [PATCH 3/5] docs: align code review with contribution guidelines --- .github/skills/code-review/SKILL.md | 35 +++++++++++++++++++++++++---- CONTRIBUTING.md | 2 +- 2 files changed, 32 insertions(+), 5 deletions(-) diff --git a/.github/skills/code-review/SKILL.md b/.github/skills/code-review/SKILL.md index b9f9438e9ad..6f50c85ac52 100644 --- a/.github/skills/code-review/SKILL.md +++ b/.github/skills/code-review/SKILL.md @@ -3,14 +3,15 @@ name: code-review description: > Review TypeSpec pull requests against the project's own rules: the Tier 0-3 breaking change policy, `.chronus` changelog requirements, compiler API usage, test framework conventions, and - emitter output stability. Use when reviewing a diff or pull request in this repository. + emitter output stability, plus contribution quality and review readiness. Use when reviewing + a diff or pull request in this repository. --- # TypeSpec code review -Review the diff against the rules this project actually enforces. Every comment must point at a -concrete problem in the changed code and cite the rule or code that makes it a problem — if you -cannot cite it, do not post it. +Review the contribution against the rules this project actually enforces. Every comment must point +at a concrete problem in the changed code or observable PR evidence and cite the rule or code that +makes it a problem — if you cannot cite it, do not post it. ## Scope @@ -38,6 +39,8 @@ Consult these and cite them in findings: and the bug exception. - `.chronus/config.yaml` — the valid `changeKind` values and the `changedFiles` exclusions. - `.github/copilot-instructions.md` — changelog message guidelines and the TDD expectation. +- `CONTRIBUTING.md` — contribution quality and review engagement expectations in + "AI-assisted contributions". - Sibling tests in the touched package — the established tester/assertion patterns. - The public compiler API (`@typespec/compiler`) and `@typespec/compiler/testing` exports — to confirm a used API exists and behaves as the change assumes. @@ -153,9 +156,33 @@ For `packages/{openapi3,openapi,json-schema,http,http-server-*}`: - Emitters must handle new type-graph shapes defensively (new node kinds, new union variants) rather than crash on them. +## 6. Contribution quality and review readiness + +Apply `CONTRIBUTING.md`'s "AI-assisted contributions" guidelines regardless of the tools used. +Use the available PR description, check results, and review threads as evidence. If only a diff is +available, state that validation and review engagement could not be verified; that is a limitation, +not itself a finding. + +- **Validation.** Check that reported results apply to the current revision and cover the affected + behavior. Identify missing relevant checks or failures that still need investigation, while + distinguishing pending checks, blocked CI, and documented baseline failures. Do not demand the + full monorepo suite for every change or treat a draft asking for help as ready for review. +- **Review engagement.** On subsequent revisions, verify that the changes address the underlying + concern, not just the wording of a comment, and preserve existing behavior. Point to a specific + unresolved concern or contradiction and ask for clarification when needed. Do not infer that the + author lacks understanding from a short reply. +- **Focus and disclosure.** Flag concrete unrelated changes or redundant tests using the same + evidence standards as other findings. If substantive AI use is explicitly known, check for the + brief disclosure required by the guidelines. Do not guess AI use from writing style, require + prompt transcripts, or treat grammar and translation assistance as violations. + +Summarize readiness issues once rather than repeating CI diagnostics or existing review comments. +The skill assists review; decisions to pause review or close a contribution remain with maintainers. + ## How to comment - One issue per comment, anchored on the offending line. +- For PR-wide readiness issues without an offending line, use one concise top-level comment. - State the problem, cite the rule (policy section, `.chronus/config.yaml`, guideline) or the relevant `file:line`, and suggest the concrete fix. - One or two sentences. No preamble, no summarizing the diff back to the author. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c076868ad95..cf03f771d6a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -365,7 +365,7 @@ We welcome contributions developed with AI assistance. These tools do not replac - **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. -Maintainers may pause review or close contributions that are unvalidated, cannot be explained by their author, or repeatedly fail to engage meaningfully with feedback. These expectations apply regardless of the tools used. +Maintainers may pause review or close contributions that have not been validated, cannot be explained by their author, or repeatedly fail to engage meaningfully with feedback. These expectations apply regardless of the tools used. ## Trigger TypeSpec Playground Try It build From 6ec451a306f6086179ee317d5651e531cfd5537f Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Wed, 4 Nov 2026 11:18:54 -0500 Subject: [PATCH 4/5] docs: simplify contribution guidance in review skill --- .github/skills/code-review/SKILL.md | 36 ++++------------------------- 1 file changed, 5 insertions(+), 31 deletions(-) diff --git a/.github/skills/code-review/SKILL.md b/.github/skills/code-review/SKILL.md index 6f50c85ac52..243e9f8ab25 100644 --- a/.github/skills/code-review/SKILL.md +++ b/.github/skills/code-review/SKILL.md @@ -3,15 +3,14 @@ name: code-review description: > Review TypeSpec pull requests against the project's own rules: the Tier 0-3 breaking change policy, `.chronus` changelog requirements, compiler API usage, test framework conventions, and - emitter output stability, plus contribution quality and review readiness. Use when reviewing - a diff or pull request in this repository. + emitter output stability. Use when reviewing a diff or pull request in this repository. --- # TypeSpec code review -Review the contribution against the rules this project actually enforces. Every comment must point -at a concrete problem in the changed code or observable PR evidence and cite the rule or code that -makes it a problem — if you cannot cite it, do not post it. +Review the diff against the rules this project actually enforces. Every comment must point at a +concrete problem in the changed code and cite the rule or code that makes it a problem — if you +cannot cite it, do not post it. ## Scope @@ -39,8 +38,7 @@ Consult these and cite them in findings: and the bug exception. - `.chronus/config.yaml` — the valid `changeKind` values and the `changedFiles` exclusions. - `.github/copilot-instructions.md` — changelog message guidelines and the TDD expectation. -- `CONTRIBUTING.md` — contribution quality and review engagement expectations in - "AI-assisted contributions". +- `CONTRIBUTING.md` — the "AI-assisted contributions" guidelines. - Sibling tests in the touched package — the established tester/assertion patterns. - The public compiler API (`@typespec/compiler`) and `@typespec/compiler/testing` exports — to confirm a used API exists and behaves as the change assumes. @@ -156,33 +154,9 @@ For `packages/{openapi3,openapi,json-schema,http,http-server-*}`: - Emitters must handle new type-graph shapes defensively (new node kinds, new union variants) rather than crash on them. -## 6. Contribution quality and review readiness - -Apply `CONTRIBUTING.md`'s "AI-assisted contributions" guidelines regardless of the tools used. -Use the available PR description, check results, and review threads as evidence. If only a diff is -available, state that validation and review engagement could not be verified; that is a limitation, -not itself a finding. - -- **Validation.** Check that reported results apply to the current revision and cover the affected - behavior. Identify missing relevant checks or failures that still need investigation, while - distinguishing pending checks, blocked CI, and documented baseline failures. Do not demand the - full monorepo suite for every change or treat a draft asking for help as ready for review. -- **Review engagement.** On subsequent revisions, verify that the changes address the underlying - concern, not just the wording of a comment, and preserve existing behavior. Point to a specific - unresolved concern or contradiction and ask for clarification when needed. Do not infer that the - author lacks understanding from a short reply. -- **Focus and disclosure.** Flag concrete unrelated changes or redundant tests using the same - evidence standards as other findings. If substantive AI use is explicitly known, check for the - brief disclosure required by the guidelines. Do not guess AI use from writing style, require - prompt transcripts, or treat grammar and translation assistance as violations. - -Summarize readiness issues once rather than repeating CI diagnostics or existing review comments. -The skill assists review; decisions to pause review or close a contribution remain with maintainers. - ## How to comment - One issue per comment, anchored on the offending line. -- For PR-wide readiness issues without an offending line, use one concise top-level comment. - State the problem, cite the rule (policy section, `.chronus/config.yaml`, guideline) or the relevant `file:line`, and suggest the concrete fix. - One or two sentences. No preamble, no summarizing the diff back to the author. From 6eae9a153374d34110e6c0c6ea39cb1d61c0b973 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Fri, 6 Nov 2026 08:49:19 -0500 Subject: [PATCH 5/5] docs: show an example of substantive AI disclosure --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cf03f771d6a..5b0058d3cfa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -363,7 +363,7 @@ We welcome contributions developed with AI assistance. These tools do not replac - **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. +- **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. For example: "AI drafted the implementation and regression test; I reviewed both and ran the package tests." Maintainers may pause review or close contributions that have not been validated, cannot be explained by their author, or repeatedly fail to engage meaningfully with feedback. These expectations apply regardless of the tools used.