Skip to content

Commit

Permalink
CONTRIBUTING.md: Fill out section on pull requests.
Browse files Browse the repository at this point in the history
  • Loading branch information
jimblandy committed Jan 29, 2025
1 parent 6c8d0b0 commit 23c20a2
Showing 1 changed file with 46 additions and 8 deletions.
54 changes: 46 additions & 8 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

0 comments on commit 23c20a2

Please sign in to comment.