Skip to content

Commit 49fb42c

Browse files
Copilotgrdsdev
Copilot
and
grdsdev
authored
chore: add Copilot instructions for AI coding agents (#843)
* Initial plan * docs: add Copilot instructions for AI coding agents Co-authored-by: grdsdev <5923044+grdsdev@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: grdsdev <5923044+grdsdev@users.noreply.github.com>
1 parent af550d7 commit 49fb42c

File tree

1 file changed

+297
-0
lines changed

1 file changed

+297
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 297 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,297 @@
1+
# Copilot Instructions for supabase-swift
2+
3+
## Repository Overview
4+
5+
This is the official Supabase SDK for Swift, mirroring the design of supabase-js. It provides a Swift client for interacting with Supabase services including Auth, Database (PostgREST), Realtime, Storage, and Functions.
6+
7+
## Project Structure
8+
9+
- `Sources/`: Source code organized by module
10+
- `Auth/`: Authentication module
11+
- `Functions/`: Edge Functions client
12+
- `PostgREST/`: Database client
13+
- `Realtime/`: Realtime subscriptions
14+
- `Storage/`: File storage client
15+
- `Supabase/`: Main client that integrates all modules
16+
- `Helpers/`: Shared utilities
17+
- `TestHelpers/`: Test utilities
18+
- `Tests/`: Unit and integration tests organized by module
19+
- `Examples/`: Example applications demonstrating SDK usage
20+
- `docs/`: Documentation files
21+
22+
## Development Environment
23+
24+
### Requirements
25+
26+
- Xcode 15.3+ (supports versions eligible for App Store submission)
27+
- Swift 5.10+
28+
- Supported platforms: iOS 13.0+, macOS 10.15+, tvOS 13+, watchOS 6+, visionOS 1+
29+
- Linux is supported for building but not officially supported for production use
30+
31+
### Build Commands
32+
33+
```bash
34+
# Build the package
35+
swift build
36+
37+
# Build for specific configuration
38+
swift build -c debug
39+
swift build -c release
40+
41+
# Build with library evolution
42+
make build-for-library-evolution
43+
44+
# Build using Xcode
45+
make PLATFORM=IOS xcodebuild
46+
make PLATFORM=MACOS xcodebuild
47+
```
48+
49+
### Testing Commands
50+
51+
```bash
52+
# Run all tests via Swift Package Manager
53+
swift test
54+
55+
# Run tests for a specific module
56+
swift test --filter AuthTests
57+
swift test --filter StorageTests
58+
59+
# Run tests via Xcode
60+
make PLATFORM=IOS XCODEBUILD_ARGUMENT=test xcodebuild
61+
62+
# Run integration tests (requires Supabase instance)
63+
make test-integration
64+
65+
# Generate code coverage
66+
make coverage
67+
```
68+
69+
### Code Formatting
70+
71+
```bash
72+
# Format all Swift files
73+
make format
74+
```
75+
76+
This uses `swift-format` to automatically format code. All code should be formatted before committing.
77+
78+
### Documentation
79+
80+
```bash
81+
# Test documentation build
82+
make test-docs
83+
```
84+
85+
Ensures DocC documentation builds without warnings.
86+
87+
## Code Style and Conventions
88+
89+
### Swift Style
90+
91+
- Use 2 spaces for indentation (configured in `.editorconfig`)
92+
- Enable strict concurrency checking (`StrictConcurrency` feature)
93+
- Use `ExistentialAny` feature for explicit existential types
94+
- Follow Swift API Design Guidelines
95+
- Prefer `async/await` over completion handlers
96+
- Mark types as `Sendable` where appropriate for concurrency safety
97+
98+
### File Headers
99+
100+
Use standard file headers with copyright:
101+
102+
```swift
103+
//
104+
// FileName.swift
105+
// ModuleName
106+
//
107+
// Created by Author Name on DD/MM/YY.
108+
//
109+
```
110+
111+
### Module Organization
112+
113+
- Each module is independent and can be used standalone
114+
- Use `@_exported import` in main Supabase module to re-export all sub-modules
115+
- Keep module dependencies minimal
116+
- Prefer protocol-oriented design
117+
118+
### Error Handling
119+
120+
- Use strongly-typed errors conforming to `Error` protocol
121+
- Provide `LocalizedError` conformance where appropriate
122+
- Use `async throws` for async error handling
123+
- Report issues using `IssueReporting` from xctest-dynamic-overlay
124+
125+
### Testing Conventions
126+
127+
- Use XCTest framework
128+
- Test files should mirror source file structure (`Foo.swift` → `FooTests.swift`)
129+
- Use `@testable import` for internal access
130+
- Use snapshot testing for complex data structures (via swift-snapshot-testing)
131+
- Use Mocker for URLSession mocking in unit tests
132+
- Use CustomDump for test assertions with better output
133+
- Keep integration tests separate in `IntegrationTests` directory
134+
135+
Example test structure:
136+
137+
```swift
138+
import XCTest
139+
@testable import ModuleName
140+
141+
final class FeatureTests: XCTestCase {
142+
func testFeatureBehavior() {
143+
// Arrange
144+
let input = "test"
145+
146+
// Act
147+
let result = feature(input)
148+
149+
// Assert
150+
XCTAssertEqual(result, expected)
151+
}
152+
}
153+
```
154+
155+
## Dependencies
156+
157+
### Core Dependencies
158+
159+
- `swift-crypto`: Cryptographic operations
160+
- `swift-http-types`: Modern HTTP types
161+
- `swift-clocks`: Time-based operations
162+
- `swift-concurrency-extras`: Concurrency utilities
163+
164+
### Test Dependencies
165+
166+
- `swift-snapshot-testing`: Snapshot testing
167+
- `swift-custom-dump`: Better test output
168+
- `xctest-dynamic-overlay`: Test utilities and issue reporting
169+
- `Mocker`: URL mocking
170+
171+
## Architecture Notes
172+
173+
### Client Initialization
174+
175+
The main `SupabaseClient` acts as a facade for all sub-clients (Auth, Database, Storage, Functions, Realtime). Each sub-client can also be used independently.
176+
177+
### Async/Await
178+
179+
The SDK is fully async/await based. Avoid using completion handlers in new code.
180+
181+
### Sendable Conformance
182+
183+
All public types should conform to `Sendable` where appropriate for Swift 6 compatibility.
184+
185+
### HTTP Layer
186+
187+
Uses modern `HTTPTypes` for request/response handling. Custom `StorageHTTPSession` abstraction allows for testing and custom implementations.
188+
189+
### Configuration
190+
191+
Uses option builder pattern for client configuration:
192+
193+
```swift
194+
SupabaseClient(
195+
supabaseURL: url,
196+
supabaseKey: key,
197+
options: SupabaseClientOptions(
198+
auth: .init(...),
199+
db: .init(...),
200+
global: .init(...)
201+
)
202+
)
203+
```
204+
205+
## Commit Conventions
206+
207+
This project uses [Conventional Commits](https://www.conventionalcommits.org/) with release-please for automated versioning:
208+
209+
- `feat:` - New features (minor version bump)
210+
- `fix:` - Bug fixes (patch version bump)
211+
- `docs:` - Documentation changes
212+
- `test:` - Test changes
213+
- `refactor:` - Code refactoring
214+
- `perf:` - Performance improvements
215+
- `chore:` - Build/tooling changes
216+
- `feat!:` or `BREAKING CHANGE:` - Breaking changes (major version bump)
217+
218+
Example: `feat(auth): add PKCE flow support`
219+
220+
## CI/CD
221+
222+
### GitHub Actions Workflows
223+
224+
- `ci.yml`: Runs tests on multiple platforms and Xcode versions
225+
- `release.yml`: Automated releases via release-please
226+
- `conventional-commits.yml`: Validates commit message format
227+
228+
### Platform Testing
229+
230+
Tests run on:
231+
232+
- macOS (iOS, macOS, Mac Catalyst, tvOS, watchOS, visionOS simulators)
233+
- Linux (build only, not fully supported)
234+
- Multiple Xcode versions (latest and legacy)
235+
236+
### Code Coverage
237+
238+
Coverage is automatically generated for iOS tests on the main CI job and uploaded to Coveralls.
239+
240+
## Support Policy
241+
242+
- **Xcode**: Only versions eligible for App Store submission
243+
- **Swift**: Minimum version from oldest-supported Xcode
244+
- **Platforms**: Four latest major versions (current + 3 previous)
245+
246+
Dropping support for older versions is NOT considered a breaking change and happens in minor releases.
247+
248+
## Common Tasks
249+
250+
### Adding a New Feature
251+
252+
1. Create feature branch from `main`
253+
2. Implement feature with tests
254+
3. Run `make format` to format code
255+
4. Run `swift test` to verify tests pass
256+
5. Add documentation if needed
257+
6. Create PR with conventional commit title
258+
7. Ensure CI passes
259+
260+
### Fixing a Bug
261+
262+
1. Add a failing test that reproduces the bug
263+
2. Fix the bug
264+
3. Verify test now passes
265+
4. Run full test suite
266+
5. Create PR with `fix:` prefix
267+
268+
### Updating Dependencies
269+
270+
Dependencies are managed in `Package.swift`. Use version ranges when possible to allow flexibility.
271+
272+
### Working with Integration Tests
273+
274+
Integration tests require a local Supabase instance:
275+
276+
```bash
277+
cd Tests/IntegrationTests
278+
supabase start
279+
supabase db reset
280+
cd ../..
281+
swift test --filter IntegrationTests
282+
cd Tests/IntegrationTests
283+
supabase stop
284+
```
285+
286+
## Important Notes for AI Coding Agents
287+
288+
- Always run `make format` before committing Swift code
289+
- Ensure new public APIs have DocC documentation comments
290+
- Add tests for all new functionality
291+
- Keep changes minimal and focused
292+
- Respect the existing architecture and patterns
293+
- Check that changes work on all supported platforms when possible
294+
- Use snapshot testing for complex response structures
295+
- Maintain Sendable conformance for Swift 6 compatibility
296+
- When adding async code, ensure proper task cancellation handling
297+
- Review the CI workflow to understand what checks will run

0 commit comments

Comments
 (0)