Development workflow

How a change moves from a local checkout to a merged PR.

Branch and commit

• Fork the repo on GitHub. PRs come from forks even for maintainers in many cases.
• Base branches off trunk. There is no main; trunk is the integration branch.
• Commit messages follow conventional-style prefixes informally: fix(core):, refactor(core):, chore(deps):, [Vulkan/hal], [Dx12/hal], [metal], etc. Browse git log --oneline for the patterns. There is no enforced format, but PR titles tend to mirror the prefix style.

Code, format, lint

cargo build
cargo fmt
cargo clippy --tests

CI runs with RUSTFLAGS=-D warnings, so a single warning will fail the build. The MSRV pins (WGPU_MSRV=1.87, CORE_MSRV=1.87, REPO_MSRV=1.93 in .github/workflows/ci.yml) are enforced; if you use a feature only available in a newer Rust release, CI will tell you.

Per AGENTS.md, don't pass --release while iterating; debug builds are noticeably faster.

Test

There is no shortcut here — cargo xtask test is the canonical test entry point and is what CI runs:

cargo xtask test
cargo xtask cts --backend vulkan       # on Linux
cargo xtask cts --backend metal        # on macOS
cargo xtask cts --backend dx12         # on Windows

For naga changes:

cargo nextest run -p naga
cargo xtask validate spv               # cd naga first

For wgpu-core changes that don't need a real GPU:

cargo nextest run --test wgpu-validation
cargo nextest run --test wgpu_trace

The full test taxonomy is in testing.md.

Update the changelog

If your change is user-visible — a documented public API change, a significant bug fix, or a new feature — add a one-liner to CHANGELOG.md under ## Unreleased in the appropriate sub-section. cargo xtask changelog (xtask/src/changelog.rs) audits this.

If you're not sure whether a change qualifies, ask in the PR.

Open a PR

• Target trunk on gfx-rs/wgpu.
• Mark as draft if you want a sanity check before formal review.
• Fill in the PR template (.github/pull_request_template.md) — checklist for tests, changelog, and behavior.
• Link the issue your PR closes if applicable.

The Assigned field on a PR indicates the maintainer shepherding the review, not the author. Maintainers self-assign or are assigned by another maintainer to make sure the PR is not forgotten.

Review and merge

• Reviewers use docs/review-checklist.md. PR authors are encouraged to self-check against the same list.
• Discussion happens inline. Squashing or rebasing happens at the author's discretion before merge; the merge queue handles the actual integration.
• Once approved, a maintainer adds the PR to the GitHub merge queue (gh-readonly-queue/* branches in .github/workflows/ci.yml). The merge queue runs CI on the post-merge state and integrates the PR if it passes.

Large PRs

CONTRIBUTING.md has a long section on this. The short version: PRs that mix multiple concerns, change semantics across many files, or introduce big new subsystems will likely be asked to break up first. Maintainers explicitly reserve the right to close large PRs that impose undue burden.

Common ways to split:

• Land preparatory refactors as no-op changes first.
• Land helpers and utilities first, even if they're unused until the next PR.
• Keep renames and code motion in their own commits or PRs.
• Land snapshot regenerations separately when feasible.

After merge

• The CHANGELOG section will roll into the next breaking release.
• Releases are cut roughly every three months. The release checklist is docs/release-checklist.md.
• If your change touches the WebGPU/WGSL implementation, downstream Firefox/Servo/Deno integrations will pick it up at their own cadence.

Useful commands cheat sheet

# build
cargo build
cargo build -p wgpu --features=trace,replay
cargo build -p naga --all-features

# format / lint / typo check
cargo fmt
cargo clippy --tests
typos

# tests
cargo xtask test
cargo nextest run -p wgpu-core
cargo nextest run -p naga
cargo nextest run --test wgpu-validation
cargo xtask cts --backend <vulkan|metal|dx12>

# examples
cargo run --bin wgpu-examples cube
cargo xtask run-wasm

# misc xtask
cargo xtask changelog
cargo xtask miri
cargo xtask install-warp