Skip to content

Latest commit

 

History

History
225 lines (175 loc) · 9.98 KB

CONTRIBUTING.md

File metadata and controls

225 lines (175 loc) · 9.98 KB

This document is a guide for contributions to the WGPU project.

Welcome!

First of all, welcome to the WGPU community! 👋 We're glad you want to contribute. If you are unfamiliar with the WGPU project, we recommend you read GOVERNANCE.md for an overview of its goals, and how it's governed.

Documentation Overview:

Talking to other humans in the WGPU project

The WGPU project has multiple official platforms for community engagement:

  • The Matrix channel wgpu:matrix.org is dedicated to informal chat about contributions the project. It is particularly useful for:

    • Saying hello, and introducing yourself.
    • Validating contributions (i.e., determining if they'll be accepted, ensuring your approach is correct, making sure you aren't wasting effort, etc.).
    • Setting expectations for contributions.

    Notification in Matrix can sometimes be unreliable. Feel free to explicitly tag people from whom you would like attention, esp. to follow-up after a day or so if you do not get a response to your contributions.

  • GitHub issues are used to discuss open development questions and track work the community intends to complete; this might include:

    • Work that needs resolution via pull requests (see below)
      • Bug reports
      • Feature requests
      • Creating new releases of crates
    • Recording project decisions formally.
      • Architectural discussion
      • ???
    • Compiling sets of other issues needed for a specific feature or use case (AKA [meta] issues).

  • GitHub pull requests: Modifications to the contents of this repository are done through pull requests.

  • wgpu Maintainership Meetings: Every week, the maintainership of the wgpu project meets to discuss the project's direction and review ongoing work. These meetings are open to the public, and you are welcome to attend. They happen on Google Meet and happen on Wednesday at 11:00 US Eastern Standard Time and last approximately an hour. Remember to obey the CODE_OF_CONDUCT.md in the meeting.

  • GitHub discussions: TODO: Experimentally used by some enthusiastic members of our community. Not supported officially.

Contributing to WGPU

Community response to contributions are, in general, prioritized based on their relevance to WGPU's mission and decision-making groups' interest (see GOVERNANCE.md).

"What can I work on?" as a new contributor

TODO

We discourage new contributors from submitting large changes or opinionated refactors unless they have been specifically validated by WGPU maintainership. These are likely to be rejected on basis of needing discussion before a formal review.

Setting up a WGPU development environment

We use the following components in a WGPU development environment:

  • A Rust toolchain matching the version specified in rust-toolchain.toml, to compile WGPU's code. If you use rustup, this will be automatically installed when you first run a cargo command in the repository.
  • Taplo to keep TOML files formatted.
  • Vulkan SDK to provide Vulkan validation layers and other Vulkan/SPIR-V tools for testing.

Once these are done, you should be ready to hack on WGPU! Drop into your favorite editor, make some changes to the repository's code, and test that WGPU has been changed the way you expect. Take a look at docs/testing.md for more info on testing.

When testing your own code against your patch, we recommend using a path dependency in Cargo for local testing of changes, and a git dependency pointing to your own fork to share changes with other contributors.

Once you are ready to request a review of your changes so they become part of WGPU public history, create a pull request with your changes committed to a branch in your own fork of WGPU in GitHub. See documentation for that here.

What to expect when you file an issue

TODO

  • Describe the filing process
    • Link to new issue page
    • Describe how to socialize the issue effectively
    • Feel free to ping us if it's a blocker!
    • Suggesting tags is helpful.
    • Describe how the project will handle the issue
      • Our ability to respond to an issue depends entirely on whether it is actionable (viz., that there is a course of action that is reasonable for a volunteer to take the time to do). If it's not actionable, we reserve the right to close it.
        • Being responsive to requests for further information is important.
        • Understanding what point in the repository's history an issue began is also important. Maybe link to git bisect or something similar?
        • In particular, expecting others to fix something hardware- or driver-specific that current maintainership (1) can't mentor you into fixing and (2) otherwise isn't being prioritized are likely to be closed.

Pull requests

You can see some common things that PR reviewers are going to look for in docs/review-checklist.md.

A draft pull request is taken to be not yet ready for review. Marking drafts as such helps the maintainers triage review work.

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.

Designing new features

As an open source project, WGPU wants to serve a broad audience. This helps us cast a wide net for contributors, and widens the impact of their work. However, WGPU does not promise to incorporate every proposed feature.

Large efforts that are ultimately rejected tend to burn contributors out on both sides of a review. To avoid this, we strongly encourage you to validate time-consuming contributions by engaging maintainership before you invest yourself too heavily. Try to build a consensus on the approach, including API changes, shader language extensions, implementation architecture, error handling, testing plans, benchmarking, and so on.

Large pull requests are risky

Contributors should anticipate that the larger and more complex a pull request is, the less likely it is that reviewers will accept it, regardless of its merits.

The WGPU project has had poor experiences with large, complex pull requests:

  • Complex pull requests are 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 reviewed and accepted, showing that we obviously hadn't understood it as well as we'd thought.

  • A large, complex 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. Such pull requests make it hard for maintainers to uphold their responsibility to keep WGPU maintainable. Incremental changes are easier to discuss and revise without drama.

These problems are serious enough that maintainers may choose to reject large, complex pull requests, regardless of the value of the feature or the technical merit of the code.

The problem isn't really the size of the pull request: a simple rename, with no changes to functionality, might touch hundreds of files, but be easy to review. Or, a change to Naga might affect dozens of snapshot test output files, without being hard to understand.

Rather, the problem is the complexity of the pull request: how many moving pieces does the reviewer need to assess at once? In our experience, almost every large change can be pared down by separating out:

  • Preparatory refactors that are at least harmless in isolation, and perhaps beneficial.

  • Helpers and utilities that can be used elsewhere in the code base, even if they don't show their full value until the whole thing is merged.

  • Renames and code motion with no semantic effect, like changes to types or behavior. When putting these in a separate pull request would be awkward, they should at least be segregated into their own commits within a pull request.

Brevity for brevity's sake is not the goal. Rather, the goal is to help the reviewer anticipate the changes' consequences. When a pull request addresses only a single issue, even if it is textually large, a trustworthy review becomes more achievable.