|
| 1 | +Guidance for AI coding agents (Copilot, Cursor, Aider, Claude, etc.) working in this repository. Human readers are welcome, but this file is written for tools. |
| 2 | + |
| 3 | +### Repository purpose |
| 4 | + |
| 5 | +This repo hosts Stream’s SwiftUI Chat SDK for iOS. It builds on the core client and provides SwiftUI-first chat components (views, view models, modifiers) for messaging apps. |
| 6 | + |
| 7 | +Agents should optimize for API stability, backwards compatibility, accessibility, and high test coverage when changing code. |
| 8 | + |
| 9 | +### Tech & toolchain |
| 10 | + • Language: Swift (SwiftUI) |
| 11 | + • Primary distribution: Swift Package Manager (SPM), secondary CocoaPods and XCFrameworks |
| 12 | + • Xcode: 15.x or newer (Apple Silicon supported) |
| 13 | + • Platforms / deployment targets: Use the values set in Package.swift/podspecs; do not lower targets without approval |
| 14 | + • CI: GitHub Actions (assume PR validation for build + tests + lint) |
| 15 | + • Linters & docs: SwiftLint and SwiftFormat |
| 16 | + |
| 17 | +### Project layout (high level) |
| 18 | + |
| 19 | +Sources/ |
| 20 | + StreamChatSwiftUI/ # SwiftUI views, view models, theming, utils |
| 21 | +Tests/ |
| 22 | + StreamChatSwiftUITests/ # Unit/UI tests for SwiftUI layer |
| 23 | + |
| 24 | +When editing near other packages (e.g., StreamChat or StreamChatUI), prefer extending the SwiftUI layer rather than duplicating logic from dependencies. |
| 25 | + |
| 26 | +### Local setup (SPM) |
| 27 | + 1. Open the repository in Xcode (root contains Package.swift). |
| 28 | + 2. Resolve packages. |
| 29 | + 3. Choose an iOS Simulator (e.g., iPhone 15) and Build. |
| 30 | + |
| 31 | +Optional: sample/demo app |
| 32 | + |
| 33 | +If a sample app target exists in this repo, prefer running that to validate UI changes. Keep demo configs free of credentials and use placeholders like YOUR_STREAM_KEY. |
| 34 | + |
| 35 | +### Schemes |
| 36 | + |
| 37 | +Typical scheme names include: |
| 38 | + • StreamChatSwiftUI |
| 39 | + • StreamChatSwiftUITests |
| 40 | + |
| 41 | +Agents must query existing schemes before invoking xcodebuild. |
| 42 | + |
| 43 | +### Build & test commands (CLI) |
| 44 | + |
| 45 | +Prefer Xcode for day-to-day work; use CLI for CI parity & automation. |
| 46 | + |
| 47 | +Build (Debug): |
| 48 | + |
| 49 | +``` |
| 50 | +xcodebuild \ |
| 51 | + -scheme StreamChatSwiftUI \ |
| 52 | + -destination 'platform=iOS Simulator,name=iPhone 15' \ |
| 53 | + -configuration Debug build |
| 54 | +``` |
| 55 | + |
| 56 | +Run tests: |
| 57 | + |
| 58 | +``` |
| 59 | +xcodebuild \ |
| 60 | + -scheme StreamChatSwiftUI \ |
| 61 | + -destination 'platform=iOS Simulator,name=iPhone 15' \ |
| 62 | + -configuration Debug test |
| 63 | +``` |
| 64 | + |
| 65 | +If a Makefile or scripts exist (e.g., make build, make test, ./scripts/lint.sh), prefer those to keep parity with CI. Discover with make help and ls scripts/. |
| 66 | + |
| 67 | +Linting & formatting |
| 68 | + • SwiftLint (strict): |
| 69 | + |
| 70 | +swiftlint --strict |
| 71 | + |
| 72 | + • Respect .swiftlint.yml and any repo-specific rules. Do not broadly disable rules; scope exceptions and justify in PRs. |
| 73 | + |
| 74 | +Public API & SemVer |
| 75 | + • Follow semantic versioning for the SwiftUI package. |
| 76 | + • Any public API change must include updated docs and migration notes. |
| 77 | + • Avoid source-breaking changes. If unavoidable, add deprecations first with a transition path. |
| 78 | + |
| 79 | +Accessibility & UI quality |
| 80 | + • Ensure components have accessibility labels, traits, and dynamic type support. |
| 81 | + • Support both light/dark mode. |
| 82 | + • When altering UI, attach before/after screenshots (or screen recordings) in PRs. |
| 83 | + |
| 84 | +Testing policy |
| 85 | + • Add/extend tests in StreamChatSwiftUITests/ for: |
| 86 | + • View models and state handling |
0 commit comments