From b48fee361783be87270e326a88e93aa0ffda1387 Mon Sep 17 00:00:00 2001 From: Damyan Pepper Date: Fri, 16 Oct 2026 16:21:16 -0700 Subject: [PATCH 1/4] [Doc] Add contribution requirements for coding agents - AGENTS.md: add 'Before contributing' stop conditions (full dev environment incl. TAEF, full test run, readable tests, issue checks, disclosure, human confirmation before opening a PR). - CLAUDE.md / GEMINI.md: import AGENTS.md for Claude Code and Gemini CLI. - copilot-instructions.md: point to AGENTS.md and have Copilot review flag skipped tests, missing disclosure and opaque binary test inputs. - AIToolPolicy.md / CONTRIBUTING.md: make the full-environment testing requirement explicit. Assisted-by: GitHub Copilot Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b940ce55-c909-4669-b068-6286a5f48d2a --- .github/copilot-instructions.md | 27 ++++++++++++ AGENTS.md | 73 +++++++++++++++++++++++++++++++++ AIToolPolicy.md | 9 ++++ CLAUDE.md | 1 + CONTRIBUTING.md | 8 ++++ GEMINI.md | 1 + 6 files changed, 119 insertions(+) create mode 100644 CLAUDE.md create mode 100644 GEMINI.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index ff7a758d2d..40898127ea 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,3 +1,30 @@ +## Contribution requirements + +Before making changes or opening a pull request, follow the "Before +contributing (read first)" section of [AGENTS.md](../AGENTS.md). It covers the +required development environment (including TAEF), required validation, test +input rules, AI-use disclosure, and the requirement that a human review every +change before a pull request is opened. + +## Pull request policy review guidance + +When reviewing pull requests, check them against [AIToolPolicy.md](../AIToolPolicy.md) and the testing +requirements in `CONTRIBUTING.md`. Raise these issues as review comments: +- The description says that tests were skipped or could not be run, for example + because TAEF, `te.exe`, a tool, or a platform was unavailable. Also flag + descriptions that report only a subset of lit suites for a functional change. + Point out that the full suite, including TAEF, must be run locally (see + "Required development environment" in `AGENTS.md`). +- The change contains substantial tool-generated content but has no + disclosure, such as an `Assisted-by:` trailer or a note in the description. + Only flag this when there are clear signs of tool generation. +- The change adds opaque binary test inputs, such as fuzzed or bit-flipped + bitcode, instead of human-readable `.hlsl` or textual `.ll` inputs. +- A functional change adds no test that would fail without the fix. + +Keep these comments factual and courteous, and link to the relevant policy +section. + ## Pull request review guidance When reviewing pull requests in this repository, always check whether `docs/ReleaseNotes.md` should be updated. diff --git a/AGENTS.md b/AGENTS.md index 36d0d7841d..e69fd3dffa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,78 @@ # DXC agent guidance +## Before contributing (read first) + +These requirements come from [AIToolPolicy.md](AIToolPolicy.md) and +[CONTRIBUTING.md](CONTRIBUTING.md). Pull requests that do not meet them are +closed or sent back. If you cannot meet a requirement, stop and tell the human +you are working with. Do not work around it, and do not open a pull request. + +### Human in the loop + +- The human contributor is the author and must be able to explain every line + of the change during review. Recommend small, focused changes, especially + for new contributors. +- Do not open a pull request (for example with `gh pr create`) until the human + has explicitly confirmed that they have read and reviewed every change, that + they understand it, and that the validation below was completed. Open pull + requests from a fork, not from a branch in this repository. +- The human must respond to review feedback personally. Do not post + auto-generated replies such as "Fixed." on the human's behalf. + +### Before starting work + +- Check that the issue is not assigned to someone and that no maintainer is + already working on it. Look at recent comments, linked pull requests, and + related open pull requests. Maintainers may have unposted fixes for recently + filed issues. Older issues are safer choices. +- Comment on the issue before starting. Discuss new features and substantial + changes with the team before writing code. + +### Required development environment + +Every pull request must be built and tested with a full development +environment: + +- Windows with Visual Studio 2019 or later, the Windows SDK, and the matching + Windows Driver Kit, which provides the TAEF test runner `te.exe`. +- Initialized submodules: `git submodule update --init --recursive`. +- See [docs/BuildingAndTestingDXC.rst](docs/BuildingAndTestingDXC.rst). + +If any part of this environment is missing, stop and tell the human. A +Linux-only or cloud environment, skipping TAEF, running only some lit suites, +or stubbing out missing tools does not meet this requirement. A pull request +description that says tests were skipped because tools were unavailable is a +policy violation. + +### Required validation + +- Build DXC and run the full test suite, including the TAEF tests, with + `hcttest` or the `check-all` target. Hardware execution tests (`hcttest + exec`) are needed only when the change affects them. +- Every functional change needs new tests. For bug fixes, at least one new + test must fail without the fix. Confirm this. +- Test inputs must be human-readable, such as `.hlsl` or textual `.ll` files. + Do not add opaque binary test inputs, such as fuzzed or bit-flipped bitcode. +- Format the changed lines with `git-clang-format`. + +### Quality of the fix + +- Fix the root cause rather than the symptom. Before patching the place where + a failure shows up, check whether the same problem has been fixed elsewhere, + and look for a more general fix. See "Investigating compile-time regressions + and miscompiles" below. +- Follow the release-note rules in `CONTRIBUTING.md`: user-visible changes go + under `### Upcoming Release` in `docs/ReleaseNotes.md`. Each entry is a + single sentence with no links to pull requests. + +### Pull request contents + +- Follow the title and description format in `CONTRIBUTING.md`. +- List the exact build configuration and test commands that were run, and + their results. +- Disclose tool use in the pull request description and in the commit + messages, for example with an `Assisted-by: ` trailer. + ## Investigating compile-time regressions and miscompiles - Start from evidence. Identify the exact pass, hot function, and triggering diff --git a/AIToolPolicy.md b/AIToolPolicy.md index bd0d062594..6830309c34 100644 --- a/AIToolPolicy.md +++ b/AIToolPolicy.md @@ -13,6 +13,15 @@ confident that the contribution is high enough quality that asking for a review is a good use of scarce maintainer time, and they should be **able to answer questions about their work during review.** +Contributors must have a **working development environment that can build DXC +and run the full test suite**, including the TAEF-based tests (see +[Building and Testing DXC](docs/BuildingAndTestingDXC.rst)). A change that has +only been partially tested because tools were unavailable is not ready for +review. This applies whether the change was written by hand or with an agent. + +Coding agents working in this repository should follow the "Before +contributing" requirements in [AGENTS.md](AGENTS.md). + We expect that new contributors will be less confident in their contributions, and our guidance to them is to **start with small contributions** that they can fully understand to build confidence. We aspire to be a welcoming community that diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8310b2de46..ac339bd4b6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,6 +36,10 @@ You can complete the CLA by going through the steps at the [Contribution License Make sure you can build the code. Familiarize yourself with the project workflow and our coding conventions. If you don't know what a pull request is read this article: . +If you use AI tools or coding agents, follow the [AI Tool Use Policy](AIToolPolicy.md). Agents should also follow the requirements in [AGENTS.md](AGENTS.md). + +Before starting work on an issue, check that it is not assigned to someone and that nobody is already working on it. Comment on the issue to say that you plan to work on it. + Before submitting a feature or substantial code contribution please discuss it with the team and ensure it follows the product roadmap. You might also read these two blogs posts on contributing code: [Open Source Contribution Etiquette](http://tirania.org/blog/archive/2010/Dec-31.html) by Miguel de Icaza and [Don't "Push" Your Pull Requests](https://www.igvita.com/2011/12/19/dont-push-your-pull-requests/) by Ilya Grigorik. Note that all code submissions will be rigorously reviewed and tested by the team, and only those that meet an extremely high bar for both quality and design/roadmap appropriateness will be merged into the source. ### Coding guidelines @@ -149,6 +153,10 @@ Changes that do not change behavior may still be required to add testing if the For bug fixes, at least one added test should fail in the absence of your non-test code changes. Tests should include reasonable permutations of the target fix/change. Include baseline changes with your change as needed. +Test inputs should be human-readable (for example `.hlsl` or textual `.ll`); avoid opaque binary test inputs. + +Before requesting review, build DXC and run the full test suite locally, including the TAEF-based tests (`hcttest` or the `check-all` target; see [Building and Testing DXC](docs/BuildingAndTestingDXC.rst)). +A pull request that has only been partially tested because tools were unavailable is not ready for review. Submitting a pull request kicks off an automated set of regression tests that verify the change introduces no unwanted changes in behavior. For a pull request to be mergeable in GitHub, it will have to pass this regression test suite. diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 0000000000..43c994c2d3 --- /dev/null +++ b/GEMINI.md @@ -0,0 +1 @@ +@AGENTS.md From 7165164bde95a912e91e9a89b44f3bda905ec945 Mon Sep 17 00:00:00 2001 From: Damyan Pepper Date: Fri, 16 Oct 2026 17:11:10 -0700 Subject: [PATCH 2/4] [Doc] Allow testing on any platform in contribution requirements Contributors are not required to use Windows or to test on every platform. Require them to run the test suite available on their platform and to have built and tested all code they add or modify, including platform-specific code. Assisted-by: GitHub Copilot Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b940ce55-c909-4669-b068-6286a5f48d2a --- .github/copilot-instructions.md | 18 ++++++++------ AGENTS.md | 44 +++++++++++++++------------------ AIToolPolicy.md | 11 ++++++--- CONTRIBUTING.md | 5 ++-- 4 files changed, 40 insertions(+), 38 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 40898127ea..9ad67a7b37 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,19 +2,21 @@ Before making changes or opening a pull request, follow the "Before contributing (read first)" section of [AGENTS.md](../AGENTS.md). It covers the -required development environment (including TAEF), required validation, test -input rules, AI-use disclosure, and the requirement that a human review every -change before a pull request is opened. +development environment and testing requirements, test input rules, AI-use +disclosure, and the requirement that a human review every change before a pull +request is opened. ## Pull request policy review guidance When reviewing pull requests, check them against [AIToolPolicy.md](../AIToolPolicy.md) and the testing requirements in `CONTRIBUTING.md`. Raise these issues as review comments: -- The description says that tests were skipped or could not be run, for example - because TAEF, `te.exe`, a tool, or a platform was unavailable. Also flag - descriptions that report only a subset of lit suites for a functional change. - Point out that the full suite, including TAEF, must be run locally (see - "Required development environment" in `AGENTS.md`). +- The description says that code added or modified by the change was not built + or tested, for example because a tool or platform was unavailable. Testing on + every platform is not required, but contributors must have tested the code + they changed, including platform-specific code such as Windows-only TAEF + tests. Also flag descriptions that say the test suite for the contributor's + platform could not be run because the development environment was + incomplete (see "Development environment and testing" in `AGENTS.md`). - The change contains substantial tool-generated content but has no disclosure, such as an `Assisted-by:` trailer or a note in the description. Only flag this when there are clear signs of tool generation. diff --git a/AGENTS.md b/AGENTS.md index e69fd3dffa..f9f9804176 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,7 +14,7 @@ you are working with. Do not work around it, and do not open a pull request. for new contributors. - Do not open a pull request (for example with `gh pr create`) until the human has explicitly confirmed that they have read and reviewed every change, that - they understand it, and that the validation below was completed. Open pull + they understand it, and that the testing below was completed. Open pull requests from a fork, not from a branch in this repository. - The human must respond to review feedback personally. Do not post auto-generated replies such as "Fixed." on the human's behalf. @@ -28,27 +28,23 @@ you are working with. Do not work around it, and do not open a pull request. - Comment on the issue before starting. Discuss new features and substantial changes with the team before writing code. -### Required development environment - -Every pull request must be built and tested with a full development -environment: - -- Windows with Visual Studio 2019 or later, the Windows SDK, and the matching - Windows Driver Kit, which provides the TAEF test runner `te.exe`. -- Initialized submodules: `git submodule update --init --recursive`. -- See [docs/BuildingAndTestingDXC.rst](docs/BuildingAndTestingDXC.rst). - -If any part of this environment is missing, stop and tell the human. A -Linux-only or cloud environment, skipping TAEF, running only some lit suites, -or stubbing out missing tools does not meet this requirement. A pull request -description that says tests were skipped because tools were unavailable is a -policy violation. - -### Required validation - -- Build DXC and run the full test suite, including the TAEF tests, with - `hcttest` or the `check-all` target. Hardware execution tests (`hcttest - exec`) are needed only when the change affects them. +### Development environment and testing + +Contributors can work on any platform DXC supports. Testing on every platform +is not required before opening a pull request. + +- Set up a working development environment for your platform, as described in + [docs/BuildingAndTestingDXC.rst](docs/BuildingAndTestingDXC.rst), including + initialized submodules (`git submodule update --init --recursive`). +- Build DXC and run the full test suite available on your platform (for + example, the `check-all` target, or `hcttest` on Windows). +- The contributor must have built and tested every piece of code that the + change adds or modifies. If the change touches platform-specific code (for + example, Windows-only TAEF tests), it must have been built and run on that + platform. If the human cannot test some of the changed code, stop and tell + them. Do not open a pull request that says changed code is untested. +- Do not work around a broken environment, for example by stubbing out missing + tools or test substitutions. - Every functional change needs new tests. For bug fixes, at least one new test must fail without the fix. Confirm this. - Test inputs must be human-readable, such as `.hlsl` or textual `.ll` files. @@ -68,8 +64,8 @@ policy violation. ### Pull request contents - Follow the title and description format in `CONTRIBUTING.md`. -- List the exact build configuration and test commands that were run, and - their results. +- List the platform, build configuration, and test commands that were run, + and their results. - Disclose tool use in the pull request description and in the commit messages, for example with an `Assisted-by: ` trailer. diff --git a/AIToolPolicy.md b/AIToolPolicy.md index 6830309c34..5faab873b5 100644 --- a/AIToolPolicy.md +++ b/AIToolPolicy.md @@ -14,10 +14,13 @@ is a good use of scarce maintainer time, and they should be **able to answer questions about their work during review.** Contributors must have a **working development environment that can build DXC -and run the full test suite**, including the TAEF-based tests (see -[Building and Testing DXC](docs/BuildingAndTestingDXC.rst)). A change that has -only been partially tested because tools were unavailable is not ready for -review. This applies whether the change was written by hand or with an agent. +and run the test suite on their platform** (see +[Building and Testing DXC](docs/BuildingAndTestingDXC.rst)). Testing on every +platform is not required before opening a pull request, but contributors must +**have built and tested the code they modified**, including platform-specific +code. A change that includes code the contributor has not tested is not ready +for review. This applies whether the change was written by hand or with an +agent. Coding agents working in this repository should follow the "Before contributing" requirements in [AGENTS.md](AGENTS.md). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ac339bd4b6..6241fdd964 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -155,8 +155,9 @@ Tests should include reasonable permutations of the target fix/change. Include baseline changes with your change as needed. Test inputs should be human-readable (for example `.hlsl` or textual `.ll`); avoid opaque binary test inputs. -Before requesting review, build DXC and run the full test suite locally, including the TAEF-based tests (`hcttest` or the `check-all` target; see [Building and Testing DXC](docs/BuildingAndTestingDXC.rst)). -A pull request that has only been partially tested because tools were unavailable is not ready for review. +Before requesting review, build DXC and run the full test suite available on your platform (see [Building and Testing DXC](docs/BuildingAndTestingDXC.rst)). +Testing on every platform is not required, but you must have built and tested all code added or modified by your change, including platform-specific code such as Windows-only TAEF tests. +A pull request that includes code the contributor has not tested is not ready for review. Submitting a pull request kicks off an automated set of regression tests that verify the change introduces no unwanted changes in behavior. For a pull request to be mergeable in GitHub, it will have to pass this regression test suite. From d78c96feaa5c6db012a4298cb3cb6a5366e5c96d Mon Sep 17 00:00:00 2001 From: Damyan Pepper Date: Fri, 16 Oct 2026 17:13:06 -0700 Subject: [PATCH 3/4] [Doc] Use PR review terminology in AGENTS.md Assisted-by: GitHub Copilot Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b940ce55-c909-4669-b068-6286a5f48d2a --- AGENTS.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f9f9804176..75903e445c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,9 +3,10 @@ ## Before contributing (read first) These requirements come from [AIToolPolicy.md](AIToolPolicy.md) and -[CONTRIBUTING.md](CONTRIBUTING.md). Pull requests that do not meet them are -closed or sent back. If you cannot meet a requirement, stop and tell the human -you are working with. Do not work around it, and do not open a pull request. +[CONTRIBUTING.md](CONTRIBUTING.md). Reviewers close, or request changes on, +pull requests that do not meet them. If you cannot meet a requirement, stop +and tell the human you are working with. Do not work around it, and do not +open a pull request. ### Human in the loop From 51ded24fdf66f2783556bcee97e58333cd200a61 Mon Sep 17 00:00:00 2001 From: Damyan Pepper Date: Fri, 16 Oct 2026 17:16:43 -0700 Subject: [PATCH 4/4] [Doc] Remove PR test reporting requirement Assisted-by: GitHub Copilot Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: b940ce55-c909-4669-b068-6286a5f48d2a --- AGENTS.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 75903e445c..1d176f2553 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -65,8 +65,6 @@ is not required before opening a pull request. ### Pull request contents - Follow the title and description format in `CONTRIBUTING.md`. -- List the platform, build configuration, and test commands that were run, - and their results. - Disclose tool use in the pull request description and in the commit messages, for example with an `Assisted-by: ` trailer.