diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index ff7a758d2d..9ad67a7b37 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,3 +1,32 @@ +## 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 +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 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. +- 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..1d176f2553 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,73 @@ # DXC agent guidance +## Before contributing (read first) + +These requirements come from [AIToolPolicy.md](AIToolPolicy.md) and +[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 + +- 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 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. + +### 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. + +### 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. + 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`. +- 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..5faab873b5 100644 --- a/AIToolPolicy.md +++ b/AIToolPolicy.md @@ -13,6 +13,18 @@ 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 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). + 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..6241fdd964 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,11 @@ 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 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. 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