docs: CHANGELOG + CONTRIBUTING.md for prerequisite PRs

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

CONTRIBUTING.md

@@ -1,108 +1,168 @@
 # 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
 
 1. Fork the repository
 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
 
 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
 
 ---