Skip to content

Commit fbd27f7

Browse files
mattleibowmattleibow
authored
Adding the initial set of AI docs (#3406)
1 parent e62d083 commit fbd27f7

17 files changed

+5476
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# GitHub Copilot Instructions for SkiaSharp
2+
3+
This file provides context for AI coding assistants working on SkiaSharp.
4+
5+
## Quick Start
6+
7+
**For quick reference:** See **[AGENTS.md](../AGENTS.md)** - 2 minute overview
8+
9+
**For practical guide:** See **[design/QUICKSTART.md](../design/QUICKSTART.md)** - 10 minute tutorial
10+
11+
**For comprehensive docs:** See **[design/](../design/)** folder
12+
13+
## Path-Specific Instructions
14+
15+
AI assistants automatically load context based on file paths from `.github/instructions/`:
16+
17+
- **C API Layer** (`externals/skia/src/c/`) → [c-api-layer.instructions.md](instructions/c-api-layer.instructions.md)
18+
- **C# Bindings** (`binding/SkiaSharp/`) → [csharp-bindings.instructions.md](instructions/csharp-bindings.instructions.md)
19+
- **Generated Code** (`*.generated.cs`) → [generated-code.instructions.md](instructions/generated-code.instructions.md)
20+
- **Native Skia** (`externals/skia/`) → [native-skia.instructions.md](instructions/native-skia.instructions.md)
21+
- **Tests** (`tests/`) → [tests.instructions.md](instructions/tests.instructions.md)
22+
- **Samples** (`samples/`) → [samples.instructions.md](instructions/samples.instructions.md)
23+
- **Documentation** (`*.md`) → [documentation.instructions.md](instructions/documentation.instructions.md)
24+
25+
See [instructions/README.md](instructions/README.md) for details.
26+
27+
## Documentation Index
28+
29+
### Essential Reading
30+
- **[AGENTS.md](../AGENTS.md)** - Quick reference (AI agents, quick lookup)
31+
- **[design/QUICKSTART.md](../design/QUICKSTART.md)** - Practical tutorial (new contributors)
32+
- **[design/README.md](../design/README.md)** - Documentation index
33+
34+
### Architecture & Concepts
35+
- **[design/architecture-overview.md](../design/architecture-overview.md)** - Three-layer architecture, design principles
36+
- **[design/memory-management.md](../design/memory-management.md)** - **Critical:** Pointer types, ownership, lifecycle
37+
- **[design/error-handling.md](../design/error-handling.md)** - Error propagation through layers
38+
39+
### Contributor Guides
40+
- **[design/adding-new-apis.md](../design/adding-new-apis.md)** - Complete step-by-step guide with examples
41+
- **[design/layer-mapping.md](../design/layer-mapping.md)** - Type mappings and naming conventions
42+
43+
## Core Principles
44+
45+
### Memory Management
46+
Three pointer types (see [memory-management.md](../design/memory-management.md)):
47+
1. **Raw (Non-Owning)** - Parameters, borrowed refs → No cleanup
48+
2. **Owned** - Canvas, Paint → Call delete on dispose
49+
3. **Ref-Counted** - Image, Shader, Data → Call unref on dispose
50+
51+
### Error Handling
52+
- **C API:** Minimal wrapper, trusts C# validation
53+
- **C#:** Validates ALL parameters, checks returns, throws exceptions
54+
55+
### Layer Boundaries
56+
- **C++ → C API:** Direct calls, type conversion
57+
- **C API → C#:** P/Invoke, parameter validation
58+
59+
## Build & Test
60+
61+
```bash
62+
# Build managed code only
63+
dotnet cake --target=libs
64+
65+
# Run tests
66+
dotnet cake --target=tests
67+
68+
# Download pre-built native libraries
69+
dotnet cake --target=externals-download
70+
```
71+
72+
## When In Doubt
73+
74+
1. Check [QUICKSTART.md](../design/QUICKSTART.md) for common patterns
75+
2. Find similar existing API and follow its pattern
76+
3. See [design/](../design/) for comprehensive details
77+
4. Verify pointer type carefully (most important!)
78+
5. Test memory management thoroughly
79+
80+
---
81+
82+
**Remember:** Three layers, three pointer types, C# is the safety boundary.

‎.github/instructions/README.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# Path-Specific Instructions for SkiaSharp
2+
3+
This directory contains path-specific instruction files that provide targeted guidance for AI coding agents working on different parts of the SkiaSharp codebase.
4+
5+
## Overview
6+
7+
Path-specific instructions automatically apply based on the files being edited, ensuring AI assistants use appropriate patterns, rules, and best practices for each layer or component.
8+
9+
## Instruction Files
10+
11+
| File | Applies To | Key Focus |
12+
|------|-----------|-----------|
13+
| **[c-api-layer.instructions.md](c-api-layer.instructions.md)** | `externals/skia/include/c/`, `externals/skia/src/c/` | C API bridging layer - no exceptions, C types, error codes |
14+
| **[csharp-bindings.instructions.md](csharp-bindings.instructions.md)** | `binding/SkiaSharp/` | C# wrappers - IDisposable, P/Invoke, validation, exceptions |
15+
| **[generated-code.instructions.md](generated-code.instructions.md)** | `*.generated.cs` files | Generated code - don't edit manually, modify templates |
16+
| **[native-skia.instructions.md](native-skia.instructions.md)** | `externals/skia/` (excluding C API) | Upstream Skia C++ - understanding only, pointer types |
17+
| **[tests.instructions.md](tests.instructions.md)** | `tests/`, `*Tests.cs` | Test code - memory management, error cases, lifecycle |
18+
| **[documentation.instructions.md](documentation.instructions.md)** | `design/`, `*.md` | Documentation - clear examples, architecture focus |
19+
| **[samples.instructions.md](samples.instructions.md)** | `samples/` | Sample code - best practices, complete examples |
20+
21+
## How It Works
22+
23+
AI coding agents that support path-specific instructions (like GitHub Copilot, Cursor, etc.) will automatically load and apply the relevant instruction file based on the file paths you're working with.
24+
25+
For example:
26+
- Editing `externals/skia/src/c/sk_canvas.cpp` → Loads **c-api-layer.instructions.md**
27+
- Editing `binding/SkiaSharp/SKCanvas.cs` → Loads **csharp-bindings.instructions.md**
28+
- Editing `tests/SKCanvasTests.cs` → Loads **tests.instructions.md**
29+
30+
## Key Benefits
31+
32+
### 1. Layer-Specific Guidance
33+
Each layer has unique requirements:
34+
- **C API:** Never throw exceptions, use C types, handle errors with return codes
35+
- **C# Bindings:** Always dispose, validate parameters, convert to C# exceptions
36+
- **Tests:** Focus on memory management, error cases, lifecycle
37+
38+
### 2. Automatic Context
39+
AI assistants automatically understand:
40+
- Which patterns to follow
41+
- What mistakes to avoid
42+
- How to handle special cases
43+
44+
### 3. Consistency
45+
Ensures all AI-generated code follows the same patterns across the codebase.
46+
47+
## Critical Concepts Covered
48+
49+
### Memory Management (All Layers)
50+
- **Raw pointers** (non-owning) - No cleanup needed
51+
- **Owned pointers** - One owner, explicit delete/dispose
52+
- **Reference-counted** - Shared ownership, ref/unref
53+
54+
### Error Handling (Per Layer)
55+
- **C API:** Catch all exceptions, return bool/null, defensive null checks
56+
- **C#:** Validate parameters, check returns, throw typed exceptions
57+
- **Tests:** Verify proper exception handling
58+
59+
### Best Practices
60+
- Proper disposal in C# (`using` statements)
61+
- Complete, self-contained examples in samples
62+
- Memory leak testing in test code
63+
- Clear documentation with examples
64+
65+
## Usage Examples
66+
67+
### For AI Assistants
68+
69+
When working on different files:
70+
71+
```
72+
# Editing C API layer
73+
externals/skia/src/c/sk_canvas.cpp
74+
→ Applies: Never throw exceptions, use SK_C_API, handle errors
75+
76+
# Editing C# wrapper
77+
binding/SkiaSharp/SKCanvas.cs
78+
→ Applies: Validate parameters, use IDisposable, throw exceptions
79+
80+
# Writing tests
81+
tests/SKCanvasTests.cs
82+
→ Applies: Use using statements, test disposal, verify no leaks
83+
```
84+
85+
### For Contributors
86+
87+
These files serve as quick reference guides for:
88+
- Understanding layer-specific requirements
89+
- Following established patterns
90+
- Avoiding common mistakes
91+
92+
## Maintaining Instructions
93+
94+
### When to Update
95+
96+
Update instruction files when:
97+
- Patterns or best practices change
98+
- New common mistakes are discovered
99+
- Layer responsibilities change
100+
- New tooling or generators are added
101+
102+
### What to Include
103+
104+
Each instruction file should cover:
105+
- ✅ Critical rules and requirements
106+
- ✅ Common patterns with code examples
107+
- ✅ What NOT to do (anti-patterns)
108+
- ✅ Error handling specifics
109+
- ✅ Memory management patterns
110+
111+
### What to Avoid
112+
113+
Don't include in instruction files:
114+
- ❌ Exhaustive API documentation
115+
- ❌ Build/setup instructions (use main docs)
116+
- ❌ Temporary workarounds
117+
- ❌ Implementation details
118+
119+
## Related Documentation
120+
121+
For comprehensive guidance, see:
122+
- **[AGENTS.md](../../AGENTS.md)** - High-level project overview for AI agents
123+
- **[design/](../../design/)** - Detailed architecture documentation
124+
- **[.github/copilot-instructions.md](../copilot-instructions.md)** - General AI assistant context
125+
126+
## Integration with AI Tools
127+
128+
These instructions integrate with:
129+
- **GitHub Copilot** - Workspace instructions
130+
- **Cursor** - .cursorrules and workspace context
131+
- **Other AI assistants** - Supporting path-specific patterns
132+
133+
## Summary
134+
135+
Path-specific instructions ensure AI coding agents apply the right patterns in the right places, maintaining code quality and consistency across SkiaSharp's three-layer architecture.
136+
137+
**Key Principle:** Different layers require different approaches - these instructions ensure AI assistants understand and apply the correct patterns for each context.

0 commit comments

Comments
 (0)