Skip to content

chore: add AGENTS.md file #845

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
grdsdev merged 1 commit into from
Nov 3, 2025
Merged

chore: add AGENTS.md file #845

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
298 changes: 7 additions & 291 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,297 +1,13 @@
# Copilot Instructions for supabase-swift

## Repository Overview

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.

## Project Structure

- `Sources/`: Source code organized by module
- `Auth/`: Authentication module
- `Functions/`: Edge Functions client
- `PostgREST/`: Database client
- `Realtime/`: Realtime subscriptions
- `Storage/`: File storage client
- `Supabase/`: Main client that integrates all modules
- `Helpers/`: Shared utilities
- `TestHelpers/`: Test utilities
- `Tests/`: Unit and integration tests organized by module
- `Examples/`: Example applications demonstrating SDK usage
- `docs/`: Documentation files

## Development Environment

### Requirements

- Xcode 15.3+ (supports versions eligible for App Store submission)
- Swift 5.10+
- Supported platforms: iOS 13.0+, macOS 10.15+, tvOS 13+, watchOS 6+, visionOS 1+
- Linux is supported for building but not officially supported for production use

### Build Commands

```bash
# Build the package
swift build

# Build for specific configuration
swift build -c debug
swift build -c release

# Build with library evolution
make build-for-library-evolution

# Build using Xcode
make PLATFORM=IOS xcodebuild
make PLATFORM=MACOS xcodebuild
```

### Testing Commands

```bash
# Run all tests via Swift Package Manager
swift test

# Run tests for a specific module
swift test --filter AuthTests
swift test --filter StorageTests

# Run tests via Xcode
make PLATFORM=IOS XCODEBUILD_ARGUMENT=test xcodebuild

# Run integration tests (requires Supabase instance)
make test-integration

# Generate code coverage
make coverage
```

### Code Formatting

```bash
# Format all Swift files
make format
```

This uses `swift-format` to automatically format code. All code should be formatted before committing.

### Documentation

```bash
# Test documentation build
make test-docs
```

Ensures DocC documentation builds without warnings.

## Code Style and Conventions

### Swift Style

- Use 2 spaces for indentation (configured in `.editorconfig`)
- Enable strict concurrency checking (`StrictConcurrency` feature)
- Use `ExistentialAny` feature for explicit existential types
- Follow Swift API Design Guidelines
- Prefer `async/await` over completion handlers
- Mark types as `Sendable` where appropriate for concurrency safety

### File Headers

Use standard file headers with copyright:

```swift
//
// FileName.swift
// ModuleName
//
// Created by Author Name on DD/MM/YY.
//
```

### Module Organization

- Each module is independent and can be used standalone
- Use `@_exported import` in main Supabase module to re-export all sub-modules
- Keep module dependencies minimal
- Prefer protocol-oriented design

### Error Handling

- Use strongly-typed errors conforming to `Error` protocol
- Provide `LocalizedError` conformance where appropriate
- Use `async throws` for async error handling
- Report issues using `IssueReporting` from xctest-dynamic-overlay

### Testing Conventions

- Use XCTest framework
- Test files should mirror source file structure (`Foo.swift` → `FooTests.swift`)
- Use `@testable import` for internal access
- Use snapshot testing for complex data structures (via swift-snapshot-testing)
- Use Mocker for URLSession mocking in unit tests
- Use CustomDump for test assertions with better output
- Keep integration tests separate in `IntegrationTests` directory

Example test structure:

```swift
import XCTest
@testable import ModuleName

final class FeatureTests: XCTestCase {
func testFeatureBehavior() {
// Arrange
let input = "test"

// Act
let result = feature(input)

// Assert
XCTAssertEqual(result, expected)
}
}
```

## Dependencies
## Instructions for Code Review

### Core Dependencies
- Check for breaking API changes
- Check if documentation is up to date
- Check if examples are up to date
- Check if tests are comprehensive and cover all critical paths

- `swift-crypto`: Cryptographic operations
- `swift-http-types`: Modern HTTP types
- `swift-clocks`: Time-based operations
- `swift-concurrency-extras`: Concurrency utilities

### Test Dependencies

- `swift-snapshot-testing`: Snapshot testing
- `swift-custom-dump`: Better test output
- `xctest-dynamic-overlay`: Test utilities and issue reporting
- `Mocker`: URL mocking

## Architecture Notes

### Client Initialization

The main `SupabaseClient` acts as a facade for all sub-clients (Auth, Database, Storage, Functions, Realtime). Each sub-client can also be used independently.

### Async/Await

The SDK is fully async/await based. Avoid using completion handlers in new code.

### Sendable Conformance

All public types should conform to `Sendable` where appropriate for Swift 6 compatibility.

### HTTP Layer

Uses modern `HTTPTypes` for request/response handling. Custom `StorageHTTPSession` abstraction allows for testing and custom implementations.

### Configuration

Uses option builder pattern for client configuration:

```swift
SupabaseClient(
supabaseURL: url,
supabaseKey: key,
options: SupabaseClientOptions(
auth: .init(...),
db: .init(...),
global: .init(...)
)
)
```

## Commit Conventions

This project uses [Conventional Commits](https://www.conventionalcommits.org/) with release-please for automated versioning:

- `feat:` - New features (minor version bump)
- `fix:` - Bug fixes (patch version bump)
- `docs:` - Documentation changes
- `test:` - Test changes
- `refactor:` - Code refactoring
- `perf:` - Performance improvements
- `chore:` - Build/tooling changes
- `feat!:` or `BREAKING CHANGE:` - Breaking changes (major version bump)

Example: `feat(auth): add PKCE flow support`

## CI/CD

### GitHub Actions Workflows

- `ci.yml`: Runs tests on multiple platforms and Xcode versions
- `release.yml`: Automated releases via release-please
- `conventional-commits.yml`: Validates commit message format

### Platform Testing

Tests run on:

- macOS (iOS, macOS, Mac Catalyst, tvOS, watchOS, visionOS simulators)
- Linux (build only, not fully supported)
- Multiple Xcode versions (latest and legacy)

### Code Coverage

Coverage is automatically generated for iOS tests on the main CI job and uploaded to Coveralls.

## Support Policy

- **Xcode**: Only versions eligible for App Store submission
- **Swift**: Minimum version from oldest-supported Xcode
- **Platforms**: Four latest major versions (current + 3 previous)

Dropping support for older versions is NOT considered a breaking change and happens in minor releases.

## Common Tasks

### Adding a New Feature

1. Create feature branch from `main`
2. Implement feature with tests
3. Run `make format` to format code
4. Run `swift test` to verify tests pass
5. Add documentation if needed
6. Create PR with conventional commit title
7. Ensure CI passes

### Fixing a Bug

1. Add a failing test that reproduces the bug
2. Fix the bug
3. Verify test now passes
4. Run full test suite
5. Create PR with `fix:` prefix

### Updating Dependencies

Dependencies are managed in `Package.swift`. Use version ranges when possible to allow flexibility.

### Working with Integration Tests

Integration tests require a local Supabase instance:

```bash
cd Tests/IntegrationTests
supabase start
supabase db reset
cd ../..
swift test --filter IntegrationTests
cd Tests/IntegrationTests
supabase stop
```
## Repository Overview

## Important Notes for AI Coding Agents
@../AGENTS.md

- Always run `make format` before committing Swift code
- Ensure new public APIs have DocC documentation comments
- Add tests for all new functionality
- Keep changes minimal and focused
- Respect the existing architecture and patterns
- Check that changes work on all supported platforms when possible
- Use snapshot testing for complex response structures
- Maintain Sendable conformance for Swift 6 compatibility
- When adding async code, ensure proper task cancellation handling
- Review the CI workflow to understand what checks will run
Loading