Try   HackMD

WebGPU team process and workflow

Onboarding

Development workflow

Making changes to WebGPU

In WGPU upstream

See wgpu:CONTRIBUTING.md.

In mozilla-central

  1. Follow Mozilla's general guidance on how to submit a patch.

  2. When writing your patch message, use r=#webgpu-reviewers or r=#webgpu-reviewers! as appropriate.

    Example patch message:

    ​​​​Bug 12341234 - do a thing in WebGPU r=#webgpu-reviewers!
    

Re-vendoring WGPU into mozilla-central

We in the WebGPU team like to re-vendor wgpu frequently, using a rotation on Google Calendar to distribute the work. We prefer a tight feedback loop with wgpu changes, so we can fix problems while it's still fresh in human minds. It's easier for a human to tackle small, frequent updates, rather than larger, less frequent ones.

N.B. that this section is linked to from bug 1851881/webgpu-update-wgpu's description.

This process is complicated. If you see anything you don't understand, give the team a holler in Matrix!

  1. ✍🏻 Ensure that you are the assignee of webgpu-update-wgpu, and file a new bug (also assigned to you) that blocks it.

    Suggestion: Name your new blocker bug something roughly associated with time, i.e., Update WGPU to upstream (week of 2023-09-28).

  2. Determine which open bugs blocked by webgpu-update-wgpu can be moved to be blocked by your newly filed blocker bug instead. Change them to depend on your new blocker bug now.

  3. πŸ“File a patch stack against your new blocker bug. Typical WGPU re-vendoring changes are created this way:

    1. Use mach vendor gfx/wgpu_bindings/moz.yaml to begin a revendor.

      mach vendor automatically calls mach vendor rust under the hood. This will inform you which cargo vet records are still outstanding, which you'll use in the next step.

    2. Now, we perform any audits necessary to run mach vendor rust to completion. You will use cargo vet certify to create audits for the outstanding versions not already covered by other auditors: https://mozilla.github.io/cargo-vet/performing-audits.html

      Example usage of cargo vet certify CLI for WGPU dependencies:

      ​​​​​​​​$ cargo vet certify --criteria=safe-to-deploy naga 22.0.0@git:… 22.0.0@git:…
      ​​​​​​​​$ cargo vet certify --criteria=safe-to-deploy wgpu-types 22.0.0@git:… 22.0.0@git:…
      ​​​​​​​​$ cargo vet certify --criteria=safe-to-deploy wgpu-hal 22.0.0@git:… 22.0.0@git:…
      ​​​​​​​​$ cargo vet certify --criteria=safe-to-deploy wgpu-core 22.0.0@git:… 22.0.0@git:…
      ​​​​​​​​$ …
      

      The above uses delta audits, which are the most common for our use case.

      Creating audit records in a WIP patch before actually auditing is fine to do, but before you actually submit these records for review, you must satisfy the criteria prompt that cargo vet shows you when you run cargo vet certify.

      This step is done once you can run mach vendor rust without any errors.

    3. Now that new dependencies have been imported, migrate first-party code as necessary until mach build works again.

    Once these steps are done, you're ready to file patches with moz-phab!

    It's strongly recommended you start your revendor patch with a WIP: prefix, so that you don't request review immediately. There's likely still more work to do to ensure your changes are ready for review.

  4. Mature your patch stack by doing a CI run against it.

    Newly vendored code often changes CI results, particularly for WebGPU CTS. We'll be using even more CLI tools to do this task in a largely automated fashion.

    1. Submit a Try push for your changes using mach try --preset webgpu.

    2. Once your run has finished, triage test results.

      1. WebGPU CTS is represented by the web-platform-test-webgpu* jobs, which are abbreviated to the webgpu* prefix in the job list. Use moz-webgpu-cts and treeherder-dl to automate the update of expected outcomes for WebGPU CTS.

        TODO: Add more detail about how to use these CLI tools with a Try push. Rough outline:

        1. Download wptreport.json files with treeherder-dl try:$rev ….
        2. Process reports with moz-webgpu-cts update-expected --glob "$reports/**/wptreport.json".
        3. Run moz-webgpu-cts update-backlog sync perma-passing.

        At time of writing, many of these CTS tests are running in webgpu-backlog* tests in tier 3, which are not visible by default. Make sure tier 3 jobs are visible when you are viewing Try pushes for WebGPU!

      2. Otherwise, triage other jobs in your Try push as one typically might.

      3. You may need to run these steps multiple times to stabilize changes, particularly is the implementation-status field of tests was changed (and they may have moved between different CI jobs as a result).

    3. Mark your patches as ready for review

    If expected outcomes for CTS have changed significantly,

  5. Once your patch stack has been landed and your new re-vendoring bug has been closed, reassign webgpu-update-wgpu to the next person in the re-vendoring rotation calendar.

πŸŽ‰Grats, you've successfully re-vendored WGPU!