gfx-rs/wpgu
repository on GitHubgpuweb/gpuweb
repository on GitHubSee wgpu
:CONTRIBUTING.md
.
mozilla-central
Follow Mozilla's general guidance on how to submit a patch.
When writing your patch message, use r=#webgpu-reviewers
or r=#webgpu-reviewers!
as appropriate.
Example patch message:
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!
βπ» 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)
.
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.
πFile a patch stack against your new blocker bug. Typical WGPU re-vendoring changes are created this way:
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.
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:
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.
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.
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.
Submit a Try push for your changes using mach try --preset webgpu
.
Once your run has finished, triage test results.
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:
wptreport.json
files with treeherder-dl try:$rev β¦
.moz-webgpu-cts update-expected --glob "$reports/**/wptreport.json"
.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!
Otherwise, triage other jobs in your Try push as one typically might.
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).
Mark your patches as ready for review
If expected outcomes for CTS have changed significantly,
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!