# WebGPU team process and workflow

## Onboarding

* You are a sub-team of the Platform Graphics team, which has its own onboarding process!
* [New hire checklist](https://docs.google.com/document/d/1wvKoR9vuP-cv3N82fOcFBIxTj8-Rj97A-JSZncQqMro/edit?usp=share_link&skip_itp2_check=true&pli=1&authuser=0)
* [Dedicated onboarding document](https://docs.google.com/document/d/1HMvMy2IqqgO9JI5kaPktVVTvYwuX1LToxjMVS5DJh_Y/edit).
* Internal Matrix channel: [WebGPU at Mozilla](https://matrix.to/#/!AQDMTeppDxxlzBSBzM:mozilla.org?via=mozilla.org&via=matrix.org)
* We meeting frequently to sync. on general WebGPU team priorities on [HackMD](https://hackmd.io/Z1m_rIm6QDO_NQMhQwEgyQ). Events are scheduled on the Platform Graphics team's calendar.
* Communities we work with the most:
* WGPU project
* [`gfx-rs/wpgu` repository on GitHub](https://github.com/gfx-rs/wgpu)
* Matrix channel: [In WebGPU We Rust](https://matrix.to/#/#wgpu:matrix.org): WGPU contributor chat
* Matrix channel: [Naga Shader Translator](https://matrix.to/#/#naga:matrix.org)
* W3C GPU Web standards
* Repository: [`gpuweb/gpuweb` repository on GitHub](https://github.com/gpuweb/gpuweb)
* Matrix channel: [WebGPU](https://matrix.to/#/#WebGPU:matrix.org)
* Interested in participation? Contact @jimblandy to get started. :slightly_smiling_face:
* We recommend that you bookmark a link to Try pushes/CI runs filtered by your contributor email, i.e., <https://treeherder.mozilla.org/jobs?repo=try&author=egubler%40mozilla.com>.
* If you're up for it, make sure you're on the rotation for doing WGPU updates.
* TODO: What else?

## Development workflow

### Making changes to WebGPU

#### In WGPU upstream

See [`wgpu`:`CONTRIBUTING.md`](https://github.com/gfx-rs/wgpu/blob/trunk/CONTRIBUTING.md).

#### In `mozilla-central`

1. Follow Mozilla's [general guidance on how to submit a patch](https://firefox-source-docs.mozilla.org/contributing/how_to_submit_a_patch.html).
2. When writing your patch message, use `r=#webgpu-reviewers` or `r=#webgpu-reviewers!` as appropriate.

:::info
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](https://calendar.google.com/calendar/u/0?cid=Y18zMGU3MzVkN2M0OWQ2MWI2NzI2MzQ2NzU3MmUzMWU4MGI1NTg0OTY3ZjJkZTk3YjE2OTdkNzVjZDdkMWEwMDAzQGdyb3VwLmNhbGVuZGFyLmdvb2dsZS5jb20) 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.

:::info
N.B. that this section is linked to from [bug 1851881/`webgpu-update-wgpu`'s description](https://bugzilla.mozilla.org/show_bug.cgi?id=1851881#c0).
:::

:::warning
This process is complicated. If you see anything you don't understand, give the team a holler in [Matrix](https://matrix.to/#/!AQDMTeppDxxlzBSBzM:mozilla.org?via=mozilla.org)!
:::

1. ✍🏻 Ensure that you are the assignee of [`webgpu-update-wgpu`](https://bugzilla.mozilla.org/show_bug.cgi?id=webgpu-update-wgpu), and file a new bug (also assigned to you) that blocks it.

:::info
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`](https://bugzilla.mozilla.org/show_bug.cgi?id=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.
4. 📝File a [patch stack](https://firefox-source-docs.mozilla.org/contributing/how_to_submit_a_patch.html) 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`](https://firefox-source-docs.mozilla.org/mozbuild/vendor/index.html) 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

:::info
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.
:::

:::warning
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.
5. 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`](https://moz-conduit.readthedocs.io/en/latest/phabricator-user.html#submitting-patches)!

:::warning
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`](https://github.com/erichdongubler-mozilla/moz-webgpu-cts/) and [`treeherder-dl`](https://github.com/erichdongubler-mozilla/treeherder-dl) to automate the update of expected outcomes for WebGPU CTS.

:::warning
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 --out-dir <dir> --artifact public/test_info/wptreport.json --job-type-re '.*web-platform-tests-webgpu.*' try:$rev`.

`treeherder-dl` will create a subdirectory for the revision in the specified output directory.

2. Process reports by running `moz-webgpu-cts update-expected --glob "$reports/**/wptreport.json"` in your Firefox tree.
3. Run `moz-webgpu-cts update-backlog sync perma-passing`.
:::

:::warning
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).

2. 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`](https://bugzilla.mozilla.org/show_bug.cgi?id=webgpu-update-wgpu) to the next person in the re-vendoring rotation calendar.

:::success
🎉Grats, you've successfully re-vendored WGPU!
:::