Skip to content

Commit 20fc342

Browse files
claudeclaude
committed
style: Format Go files and add Claude development guidelines
- Run gofmt on all WebGPU-related files - Add CLAUDE.md with pre-commit requirements: - Code formatting (gofmt) - Linting (go vet) - Testing (go test) - Build verification - Document Git workflow and commit message format - Add code style guidelines for Go/WASM - Document WebGPU-specific best practices - Include common pitfalls and error recovery guidance This ensures consistent code quality and provides clear guidelines for future development work on the Guix codebase.
1 parent d7e0c93 commit 20fc342

7 files changed

Lines changed: 332 additions & 100 deletions

File tree

‎CLAUDE.md‎

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
# Claude Development Guidelines for Guix
2+
3+
This document contains guidelines and rules for Claude when working on the Guix codebase.
4+
5+
## Pre-Commit Requirements
6+
7+
Before committing any changes, Claude must ensure the following checks pass:
8+
9+
### 1. Code Formatting
10+
11+
All Go files must be formatted with `gofmt`:
12+
13+
```bash
14+
gofmt -w .
15+
```
16+
17+
This ensures consistent code style across the entire codebase.
18+
19+
### 2. Linting
20+
21+
Run `go vet` to catch common Go mistakes:
22+
23+
```bash
24+
go vet ./...
25+
```
26+
27+
### 3. Testing
28+
29+
Run all tests to ensure no regressions:
30+
31+
```bash
32+
go test ./...
33+
```
34+
35+
All tests must pass before committing.
36+
37+
### 4. Build Verification
38+
39+
Verify the code compiles for both native and WASM targets:
40+
41+
```bash
42+
# Native build
43+
go build ./...
44+
45+
# WASM build (for runtime package)
46+
GOOS=js GOARCH=wasm go build ./pkg/runtime/...
47+
```
48+
49+
## Complete Pre-Commit Checklist
50+
51+
Run these commands before every commit:
52+
53+
```bash
54+
# Format all Go files
55+
gofmt -w .
56+
57+
# Check for common mistakes
58+
go vet ./...
59+
60+
# Run tests
61+
go test ./...
62+
63+
# Verify native build
64+
go build ./...
65+
66+
# Verify WASM build
67+
GOOS=js GOARCH=wasm go build ./pkg/runtime/...
68+
```
69+
70+
## Git Workflow
71+
72+
### Commit Message Format
73+
74+
Commit messages should follow this format:
75+
76+
```
77+
<type>: <subject>
78+
79+
<body>
80+
81+
<footer>
82+
```
83+
84+
**Types:**
85+
- `feat`: New feature
86+
- `fix`: Bug fix
87+
- `docs`: Documentation changes
88+
- `style`: Code style changes (formatting, missing semicolons, etc.)
89+
- `refactor`: Code refactoring
90+
- `test`: Adding or updating tests
91+
- `chore`: Maintenance tasks
92+
93+
**Example:**
94+
```
95+
feat: Add WebGPU support for 3D graphics
96+
97+
Implement comprehensive WebGPU runtime with scene graphs,
98+
PBR materials, and lighting system.
99+
100+
- Add 8 new runtime modules for GPU operations
101+
- Create rotating cube example
102+
- Add detailed documentation in docs/WEBGPU.md
103+
```
104+
105+
### Branch Naming
106+
107+
Feature branches should follow the pattern: `claude/<feature-name>-<session-id>`
108+
109+
Example: `claude/add-webgpu-support-01BWtA2VBNZfg7Y29aanCzJG`
110+
111+
### Before Pushing
112+
113+
Always verify the build passes on CI/CD before pushing:
114+
115+
1. Format code: `gofmt -w .`
116+
2. Run linter: `go vet ./...`
117+
3. Run tests: `go test ./...`
118+
4. Build all targets: `go build ./...`
119+
5. Commit changes
120+
6. Push to remote
121+
122+
## Code Style Guidelines
123+
124+
### General Go Style
125+
126+
Follow the [Effective Go](https://go.dev/doc/effective_go) guidelines:
127+
128+
- Use `gofmt` for formatting (enforced pre-commit)
129+
- Keep functions small and focused
130+
- Use meaningful variable names
131+
- Comment exported functions and types
132+
- Avoid global mutable state
133+
134+
### WASM-Specific Code
135+
136+
For code in `pkg/runtime/`:
137+
138+
- Always use build tags: `//go:build js && wasm`
139+
- Handle `js.Value` carefully - check `Truthy()` before use
140+
- Clean up `js.Func` with `Release()` to prevent memory leaks
141+
- Use lowercase function names for internal helpers (e.g., `logError`, not `LogError`)
142+
143+
### WebGPU Code
144+
145+
For WebGPU-related code:
146+
147+
- Validate GPU context before operations
148+
- Handle async promises with proper error checking
149+
- Log errors using `logError()` from `dom.go`
150+
- Clean up GPU resources in cleanup/unmount methods
151+
- Test in WebGPU-enabled browsers (Chrome 113+, Edge 113+)
152+
153+
## Testing Guidelines
154+
155+
### Unit Tests
156+
157+
- Place tests in `*_test.go` files
158+
- Use table-driven tests where appropriate
159+
- Mock external dependencies
160+
- Test error cases, not just happy paths
161+
162+
### Integration Tests
163+
164+
- Test WASM builds with browser automation (when available)
165+
- Verify WebGPU functionality in supported browsers
166+
- Test example applications end-to-end
167+
168+
## Documentation
169+
170+
### Code Documentation
171+
172+
- Add godoc comments to all exported types and functions
173+
- Include examples in documentation where helpful
174+
- Keep comments up-to-date with code changes
175+
176+
### User Documentation
177+
178+
- Update README.md for user-facing changes
179+
- Add detailed guides to `docs/` for major features
180+
- Include working examples in `examples/`
181+
- Document browser compatibility requirements
182+
183+
## Common Pitfalls to Avoid
184+
185+
### Go/WASM Issues
186+
187+
1. **Unused imports**: Remove all unused imports (build will fail)
188+
2. **Name conflicts**: Can't have type and function with same name in package
189+
3. **Case sensitivity**: Exported names start with uppercase, internal with lowercase
190+
4. **js.Value lifecycle**: Always check `Truthy()` and release `js.Func`
191+
192+
### WebGPU Issues
193+
194+
1. **Async initialization**: WebGPU requires async setup via promises
195+
2. **Context configuration**: Canvas context must be configured before use
196+
3. **Resource cleanup**: Always destroy GPU resources (buffers, textures, etc.)
197+
4. **Browser support**: Check WebGPU availability before use
198+
199+
## CI/CD Expectations
200+
201+
The continuous integration system will run:
202+
203+
1. `gofmt -d .` (check formatting)
204+
2. `go vet ./...` (linting)
205+
3. `go test ./...` (tests)
206+
4. `go build ./...` (build verification)
207+
5. `GOOS=js GOARCH=wasm go build ./pkg/runtime/...` (WASM build)
208+
209+
All checks must pass for the build to succeed.
210+
211+
## Error Recovery
212+
213+
If the build fails:
214+
215+
1. Read the error message carefully
216+
2. Fix the specific issue (formatting, imports, syntax)
217+
3. Re-run the pre-commit checklist
218+
4. Commit the fix with a descriptive message
219+
5. Push the corrected code
220+
221+
## Resources
222+
223+
- [Go Documentation](https://go.dev/doc/)
224+
- [Effective Go](https://go.dev/doc/effective_go)
225+
- [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
226+
- [WebGPU Specification](https://www.w3.org/TR/webgpu/)
227+
- [syscall/js Package](https://pkg.go.dev/syscall/js)
228+
229+
---
230+
231+
**Last Updated**: 2025-11-28
232+
**Version**: 1.0

‎examples/webgpu-cube/main.go‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,15 @@ package main
44

55
import (
66
"fmt"
7-
"syscall/js"
87
"github.com/gaarutyunov/guix/pkg/runtime"
8+
"syscall/js"
99
)
1010

1111
var (
12-
rotationX float32 = 0
13-
rotationY float32 = 0
14-
autoRotate bool = true
15-
speed float32 = 1.0
12+
rotationX float32 = 0
13+
rotationY float32 = 0
14+
autoRotate bool = true
15+
speed float32 = 1.0
1616
)
1717

1818
func main() {

‎pkg/runtime/gpu_canvas.go‎

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -14,22 +14,22 @@ type GPUCanvas struct {
1414
GPUContext *GPUContext // Shared GPU context
1515
Width int
1616
Height int
17-
Format string // Texture format (e.g., "bgra8unorm")
18-
FrameCallback js.Func // Animation frame callback
17+
Format string // Texture format (e.g., "bgra8unorm")
18+
FrameCallback js.Func // Animation frame callback
1919
RenderFunc func(*GPUCanvas, float64) // User render function
20-
AnimationID js.Value // requestAnimationFrame ID
20+
AnimationID js.Value // requestAnimationFrame ID
2121
Running bool
2222
FrameCount int
2323
LastTime float64
2424
}
2525

2626
// GPUCanvasConfig holds configuration for creating a GPU canvas
2727
type GPUCanvasConfig struct {
28-
Width int
29-
Height int
28+
Width int
29+
Height int
3030
DevicePixelRatio float64
31-
AlphaMode string // "opaque", "premultiplied"
32-
FrameLoop string // "always", "demand", "never"
31+
AlphaMode string // "opaque", "premultiplied"
32+
FrameLoop string // "always", "demand", "never"
3333
}
3434

3535
// DefaultGPUCanvasConfig returns default canvas configuration
@@ -75,8 +75,8 @@ func CreateGPUCanvas(config GPUCanvasConfig) (*GPUCanvas, error) {
7575

7676
// Configure the canvas context
7777
configObj := map[string]interface{}{
78-
"device": gpuCtx.Device,
79-
"format": format,
78+
"device": gpuCtx.Device,
79+
"format": format,
8080
"alphaMode": config.AlphaMode,
8181
}
8282
gpuCanvasCtx.Call("configure", configObj)
@@ -198,8 +198,8 @@ func (gc *GPUCanvas) BeginRenderPass(encoder js.Value, clearColor [4]float32, lo
198198

199199
// Create color attachment descriptor
200200
colorAttachment := map[string]interface{}{
201-
"view": textureView,
202-
"loadOp": loadOp,
201+
"view": textureView,
202+
"loadOp": loadOp,
203203
"storeOp": "store",
204204
}
205205

@@ -246,16 +246,16 @@ func (gc *GPUCanvas) BeginRenderPassWithDepth(
246246

247247
// Create depth attachment
248248
depthAttachment := map[string]interface{}{
249-
"view": depthTexture.Call("createView"),
250-
"depthLoadOp": depthLoadOp,
251-
"depthStoreOp": "store",
249+
"view": depthTexture.Call("createView"),
250+
"depthLoadOp": depthLoadOp,
251+
"depthStoreOp": "store",
252252
"depthClearValue": depthClearValue,
253253
}
254254

255255
// Create color attachment
256256
colorAttachment := map[string]interface{}{
257-
"view": textureView,
258-
"loadOp": "clear",
257+
"view": textureView,
258+
"loadOp": "clear",
259259
"storeOp": "store",
260260
"clearValue": map[string]interface{}{
261261
"r": clearColor[0],
@@ -267,7 +267,7 @@ func (gc *GPUCanvas) BeginRenderPassWithDepth(
267267

268268
// Create render pass descriptor
269269
renderPassDescriptor := map[string]interface{}{
270-
"colorAttachments": []interface{}{colorAttachment},
270+
"colorAttachments": []interface{}{colorAttachment},
271271
"depthStencilAttachment": depthAttachment,
272272
}
273273

@@ -287,8 +287,8 @@ func (gc *GPUCanvas) Resize(width, height int) error {
287287

288288
// Reconfigure GPU context
289289
configObj := map[string]interface{}{
290-
"device": gc.GPUContext.Device,
291-
"format": gc.Format,
290+
"device": gc.GPUContext.Device,
291+
"format": gc.Format,
292292
"alphaMode": "premultiplied",
293293
}
294294
gc.Context.Call("configure", configObj)

0 commit comments

Comments
 (0)