diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index eacf57549e..32980dd509 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -121,11 +121,49 @@ TODO into fixing and (2) otherwise isn't being prioritized are likely to be closed. -### What to expect when you submit a PR - -TODO: It is strongly recommended that you validate your contributions before -you make significant efforts… - -The "Assigned" field on a PR indicates who has taken responsibility -for reviewing the PR, not who is responsible for the content of the -PR. +### Pull requests + +The "Assigned" field on a pull request indicates who has taken +responsibility for shepherding it through the review process, not who +is responsible for authoring it. The assignee is usually the reviewer, +but they can also delegate the review to someone else. The intent of +assignment is simply to ensure that pull requests don't get neglected. + +A draft pull request is taken to be not yet ready for review. Marking +drafts as such helps the maintainers triage review work. + +When one pull request builds on another, please put "Depends on #NNNN" +towards the top of its description. This helps maintainers notice that +they shouldn't merge it until its ancestor has been approved. Don't +use the "draft pull request" status to indicate dependency. + +If a pull request contains multiple commits, please indicate whether +they need to be squashed into a single commit before they're merged, +or if they're ready to rebase onto `trunk` as they stand. In the +latter case, please ensure that each commit passes all CI tests, so +that we can continue to bisect along `trunk` to isolate bugs. + +Pull requests should not contain merge commits. Please rebase on +`trunk` before submitting a pull request. (Draft pull requests may +contain anything you like.) + +#### Large pull requests are not accepted + +Large projects must be broken into series of smaller pull requests +that can be reviewed and discussed independently. WGPU's experience +with large, complex pull requests has been bad enough that we now +simply reject them, without trying to assess their merits. + +- Large pull requests are very difficult to review effectively. It is + common for us to debug a problem in WGPU and find that it was + introduced by some massive pull request that we had accepted, + showing that we obviously hadn't understood it as well as we'd + thought. + +- A giant pull request obviously represents a significant effort on + the part of the author. At a personal level, it is quite stressful + to question its design decisions, knowing that changing them will + require the author to essentially reimplement the project from + scratch. Giant pull requests effectively arrogate the ability to + make design decisions from the maintainers, whereas incremental + changes can be discussed and revised without drama.