diff --git a/CHANGELOG.md b/CHANGELOG.md index a43e162..83590d2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,48 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [Unreleased] + +### Fixed + +- **Device teardown GPU drain ordering** — `Device.Release()` now drains GPU work + via internal `waitIdle()` before destroying staging buffers and encoders. + Previously, the public `WaitIdle()` returned `ErrReleased` immediately due to + the released flag, leaving in-flight submissions unreferenced. Matches Rust + wgpu `Queue::Drop` ordering. Contributor: @besmpl (#264). + +- **Vulkan swapchain fail-closed lifecycle** — surface capabilities are fully + validated before committing to state changes, semaphore/fence errors propagate + instead of being silently ignored, and swapchain reconfiguration is transactional + (old swapchain survives until replacement is ready). Adds `broken` flag to prevent + reuse after synchronization failures. Contributor: @besmpl (#265). + +- **Explicit mock adapter construction** — `core.NewInstance` no longer fabricates + a mock adapter when no HAL backend yields adapters. Registration failures are + now observable. Tests that need a deterministic adapter opt in via + `NewInstanceWithMock`. Matches Rust wgpu behavior. Contributor: @besmpl (#266). + +- **Surface lifetime ownership** — centralized acquisition/teardown with opaque + lease system that invalidates retained texture wrappers on present/discard/ + unconfigure/destruction. Instance owns deterministic release ordering (devices + before surfaces before native instance). Vulkan HAL gains device-level swapchain + tracking with orderly and device-loss abandon paths. + Contributor: @besmpl (#269). + +### Added + +- **Surface-qualified adapter selection** — `RequestAdapterWithSurface` validates + adapters against the target surface's presentation queue via + `vkGetPhysicalDeviceSurfaceSupportKHR`. Creates request-local adapter wrappers + that carry the proven queue family into `Open()`, keeping cached adapters + immutable. Iterates all queue families — ahead of Rust wgpu which hardcodes + `queue_family_index = 0`. Contributor: @besmpl (#267). + +### Changed + +- **CONTRIBUTING.md** — Smart Coding framework (AI-assisted policy), updated + project structure, pre-submit checklist with cross-platform lint. + ## [0.30.22] - 2026-07-16 ### Fixed diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 95af33a..4a180ad 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,48 @@ # Contributing to wgpu -Thank you for your interest in contributing to wgpu! +Thank you for your interest in contributing to the Pure Go WebGPU implementation! + +wgpu is part of the [gogpu](https://github.com/gogpu) ecosystem — 1.1M+ lines of Pure Go GPU code powering 2D graphics, 3D rendering, GUI toolkit, ML frameworks, and a game engine. + +## AI-Assisted Contributions: Smart Coding Welcome + +**We welcome AI-assisted contributions.** This entire ecosystem is built using AI-assisted workflows, and we don't consider AI assistance a negative signal. What matters is the quality of the result, not the tool used to produce it. + +We practice [**Smart Coding**](https://dev.to/kolkov/from-vibe-coding-to-agentic-engineering-what-karpathy-got-right-and-whats-missing-62e) — a framework where human engineering judgment drives AI capabilities. The key insight: **you own architecture, AI owns implementation**. The 70/30 rule applies — spend 70% of effort on architecture, review, and validation; 30% on implementation. + +There are three paradigms on the AI-assisted development spectrum: + +| | Vibe Coding | Agentic Engineering | Smart Coding | +|---|---|---|---| +| **Approach** | "Give in to the vibes, forget code exists" (Karpathy) | Orchestrate AI agents with specs and quality gates | Meta-framework: engineering judgment decides when to explore vs. build | +| **Strengths** | Fast prototyping, feasibility spikes | Parallel workflows, specification-driven | Knowledge compounds across sessions, bidirectional learning | +| **Weakness** | Production disasters without oversight | "Like conducting an orchestra that can't remember yesterday's piece" | Requires experienced engineers who understand the domain | +| **Our verdict** | Good for exploration, never for production | Good foundation, missing feedback loop | **This is what we practice** | + +**What separates Smart Coding from low-quality AI-generated code:** + +| Smart Coding | Low-Quality AI Code | +|---|---| +| Understands the reference implementation (Rust wgpu) | Copy-pastes without understanding the architecture | +| Researches before coding — consults enterprise references | "Insert call and see what happens" | +| Tests on real hardware and real examples | "Build passes, ship it" | +| Handles edge cases and error paths | Happy path only | +| Can explain design decisions when asked | "The AI suggested it" | +| Clean commit history with meaningful messages | Single 10K-line commit with "add feature" | +| Iterates on review feedback with understanding | Regenerates entire file and hopes for the best | + +**What we look for in any contribution, AI-assisted or not:** + +- Evidence that you understand what the code does and why +- Rust wgpu reference consulted for non-trivial changes (we port from [gfx-rs/wgpu](https://github.com/gfx-rs/wgpu)) +- Tests that verify behavior, not just compilation +- Willingness to iterate on review feedback + +**We do NOT require:** + +- Disclosure of AI tool usage — it's your choice +- "Hand-written" code — we care about correctness, not process +- Perfect first submission — we'll work with you to get it right ## Getting Started @@ -8,49 +50,64 @@ Thank you for your interest in contributing to wgpu! 2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/wgpu` 3. Create a branch: `git checkout -b feat/your-feature` 4. Make your changes -5. Run tests: `go test ./...` -6. Commit: `git commit -m "feat: add your feature"` +5. Run checks (see below) +6. Commit using [Conventional Commits](https://www.conventionalcommits.org/) 7. Push: `git push origin feat/your-feature` 8. Open a Pull Request ## Development Setup ```bash -# Clone the repository git clone https://github.com/gogpu/wgpu cd wgpu -# Install dependencies go mod download - -# Run tests +go build ./... go test ./... +golangci-lint run --timeout=5m +``` + +**Requirements:** Go 1.25+, `golangci-lint`, `CGO_ENABLED=0` (pure Go, no C compiler needed). + +## Pre-Submit Checklist -# Run linter -golangci-lint run +Run these before pushing: + +```bash +go fmt ./... # Format +go vet ./... # Vet +golangci-lint run --timeout=5m # Lint +go build ./... # Build +go test ./... # Test ``` -## Code Style +For platform-specific changes, lint on all target platforms: + +```bash +GOOS=linux GOARCH=amd64 golangci-lint run --timeout=5m +GOOS=darwin GOARCH=arm64 golangci-lint run --timeout=5m +``` -- Follow standard Go conventions -- Use `gofmt` for formatting -- Use `golangci-lint` for linting -- Write tests for new functionality -- Document public APIs +Platform-specific files (`_darwin.go`, `_linux.go`, `_windows.go`) are invisible to lint on other platforms. ## Project Structure ``` wgpu/ -├── types/ # WebGPU type definitions -├── core/ # Core validation and state tracking -├── hal/ # Hardware abstraction layer -│ ├── vulkan/ # Vulkan backend -│ ├── metal/ # Metal backend -│ ├── dx12/ # DirectX 12 backend -│ └── gl/ # OpenGL backend -├── internal/ # Internal utilities -└── cmd/ # CLI tools (if any) +├── *.go # Public API (20 types wrapping core/ and hal/) +├── core/ # Validation, resource management, state tracking +│ └── track/ # Buffer/resource state tracking +├── hal/ # Hardware abstraction layer (interfaces + descriptors) +│ ├── vulkan/ # Vulkan backend (Windows, Linux, macOS, Android) +│ ├── metal/ # Metal backend (macOS, iOS) +│ ├── dx12/ # DirectX 12 backend (Windows) +│ ├── gles/ # OpenGL ES backend (Windows, Linux) +│ ├── software/ # Software rasterizer + SPIR-V interpreter +│ ├── noop/ # No-op backend (testing) +│ └── allbackends/ # Backend registration convenience +├── internal/ # Internal utilities +├── cmd/ # CLI tools and test apps +└── examples/ # Example applications ``` ## Commit Messages @@ -58,51 +115,54 @@ wgpu/ We use [Conventional Commits](https://www.conventionalcommits.org/): ``` -feat(component): add new feature -fix(component): fix bug -docs: update documentation -test: add tests -refactor: code refactoring -chore: maintenance tasks +feat(vulkan): add Android arm64 WSI support +fix(metal): pin autorelease pools to OS threads +docs: update ARCHITECTURE.md +test(core): add surface lifecycle tests +refactor(hal): share checked swapchain enumeration +chore: bump dependencies ``` -Components: `types`, `core`, `hal`, `vulkan`, `metal`, `dx12`, `gl`, `docs`, `ci` +Components: `core`, `hal`, `vulkan`, `metal`, `dx12`, `gles`, `software`, `noop`, `docs`, `ci` ## Pull Request Guidelines - Keep PRs focused on a single change +- Reference the Rust wgpu equivalent for non-trivial HAL/core changes +- Add tests for new functionality - Update documentation if needed -- Add tests for new features -- Ensure all tests pass +- Ensure all CI checks pass - Reference related issues +For large features, consider splitting into a prerequisite stack — small, reviewable PRs that build on each other. We take responsibility for every line that lands in the codebase. + ## Testing -### Unit Tests ```bash -go test ./... +go test ./... # Unit tests +go test -cover ./... # With coverage +go test -race ./... # With race detector (requires CGO_ENABLED=1) ``` -### With Coverage -```bash -go test -cover ./... -``` +For backend-specific verification, run examples with backend selection: -### With Race Detector ```bash -go test -race ./... +GOGPU_GRAPHICS_API=vulkan go run ./examples/compute-sum/ +GOGPU_GRAPHICS_API=dx12 go run ./examples/compute-sum/ +GOGPU_GRAPHICS_API=software go run ./examples/compute-sum/ ``` ## Reporting Issues -- Use GitHub Issues -- Include Go version and OS +- Use [GitHub Issues](https://github.com/gogpu/wgpu/issues) +- Include Go version, OS, and GPU (if relevant) - Provide minimal reproduction -- Include error messages +- Include error messages and backend used (`GOGPU_GRAPHICS_API=?`) ## Questions? -Open a GitHub Discussion or reach out to maintainers. +- [GitHub Discussions](https://github.com/orgs/gogpu/discussions) for questions and ideas +- PR comments for code-specific discussion ---