|
| 1 | +# Repository Guidelines |
| 2 | + |
| 3 | +Guidance for AI coding agents (Copilot, Cursor, Aider, Claude, etc.) working in Stream’s Android Chat repo. Humans are welcome too; tone is optimised for tools. |
| 4 | + |
| 5 | +### Repository purpose |
| 6 | +This project delivers **Stream Chat Android**, a modular SDK spanning low-level client APIs, offline persistence, and both Compose and XML UI kits. Treat it as customer-facing product code: changes ripple to thousands of apps, so prioritise stability, binary compatibility, and polished UX. |
| 7 | + |
| 8 | +### Tech & toolchain |
| 9 | +- Language: Kotlin (JVM target 11 across modules) with limited Java interop |
| 10 | +- Android min/target: 21 / 34 (verify in `gradle/libs.versions.toml` before raising) |
| 11 | +- UI stacks: Jetpack Compose, classic Views, baseline profiles for performance |
| 12 | +- Networking & storage: OkHttp, Retrofit + Moshi, Room, Coil, WorkManager |
| 13 | +- Build: Gradle Kotlin DSL + `buildSrc/` conventions, version catalogs in `gradle/` |
| 14 | +- Static analysis: Spotless (ktlint, XML headers), Detekt, API validator, Jacoco + Sonar |
| 15 | +- Testing: JUnit4/5, Mockito-Kotlin, Turbine, Robolectric, Espresso, Paparazzi, Shot |
| 16 | + |
| 17 | +## Project structure |
| 18 | +- `stream-chat-android-client/` – core API client, REST/WebSocket, plugin hooks |
| 19 | +- `stream-chat-android-offline/` – persistence, sync, caching, retry workers |
| 20 | +- `stream-chat-android-state/` – state container shared by UI layers |
| 21 | +- `stream-chat-android-ui-common/` – theming, assets, shared UI helpers |
| 22 | +- `stream-chat-android-compose/` & `stream-chat-android-ui-components/` – Compose and XML UI kits |
| 23 | +- `*-sample/`, `stream-chat-android-ui-uitests/`, `stream-chat-android-test/` – samples, integration, and shared test harnesses |
| 24 | +- `buildSrc/`, `config/`, `scripts/`, `fastlane/`, `metrics/` – build logic, lint configs, automation, release metrics, CI helpers |
| 25 | + |
| 26 | +> Modules are published; avoid leaking internal types across boundaries without coordinating version policy and changelog updates. |
| 27 | +
|
| 28 | +## Build, test, and validation |
| 29 | +- Format/licence: `./gradlew spotlessApply` |
| 30 | +- Static analysis: `./gradlew detekt` or module-scoped `:module:detekt` |
| 31 | +- Unit tests: `./gradlew testDebugUnitTest` (or `:module:test` for non-Android modules) |
| 32 | +- UI snapshots: `./gradlew verifyPaparazziDebug` (Compose) / `./gradlew shotVerify` (Views) |
| 33 | +- Instrumented suites: `./gradlew connectedAndroidTest` or targeted `:stream-chat-android-ui-uitests:connectedCheck` |
| 34 | +- Full gate: `./gradlew check` |
| 35 | + |
| 36 | +Prefer module-scoped tasks while iterating; PRs should pass `spotlessCheck`, `detekt`, and relevant unit/UI suites before review. |
| 37 | + |
| 38 | +## Coding principles |
| 39 | +- **API stability**: Public APIs are validated; favour additive changes and mark deprecations with clear migration paths (`DEPRECATIONS.md`). |
| 40 | +- **Offline-first**: Respect sync contracts in offline/state modules—guard race conditions, idempotency, and background workers. |
| 41 | +- **UI parity**: Keep Compose and XML kits behaviourally aligned; update shared fixtures/tests when touching one side. |
| 42 | +- **Performance**: Maintain lazy flows, paging, and baseline profiles; avoid extra recompositions or heavy main-thread work. |
| 43 | +- **Customisability**: Expose configuration via theming, factories, or style slots rather than hard-coded branching. |
| 44 | +- **Logging & analytics**: Use provided logging abstractions; never leak user PII or tokens. |
| 45 | + |
| 46 | +## Style & conventions |
| 47 | +- Spotless-enforced Kotlin style (4 spaces, no wildcard imports, licence headers). Run `./gradlew spotlessCheck` in CI parity. |
| 48 | +- Compose components follow noun-based naming (`MessageList`, `ChannelListHeader`); previews use `@StreamPreview` helpers. |
| 49 | +- Use `@OptIn` annotations explicitly; avoid suppressions unless documented. |
| 50 | +- Backtick test names (for example: ``fun `message list filters muted channels`()``) for readability; keep helper extensions private/internal. |
| 51 | +- Document public APIs with KDoc, including thread expectations and state notes. |
| 52 | + |
| 53 | +## Testing guidance |
| 54 | +- Place JVM tests in `src/test/java|kotlin`, Android/UI tests in `src/androidTest` or dedicated UI test modules. |
| 55 | +- Compose UI regressions: add Paparazzi snapshots and run `verifyPaparazziDebug`; record Shot baselines when behaviour changes in XML kit. |
| 56 | +- Exercise chat flows with provided fakes (`stream-chat-android-test`) and ensure offline ↔ client boundaries are covered. |
| 57 | +- For concurrency-sensitive logic (uploads, sync, message state), add deterministic tests using `runTest` + virtual time. |
| 58 | +- Update baseline profiles (`baseline-prof.txt`) when start-up or scroll performance changes significantly. |
| 59 | + |
| 60 | +## Documentation & comments |
| 61 | +- Update module README, `docs/`, or API docs when altering setup, themes, or sample flows. |
| 62 | +- Log deprecations or behavioural shifts in `CHANGELOG.md` and `DEPRECATIONS.md`. |
| 63 | +- Keep inline comments focused on intent (why), not mechanics; prefer KDoc for public APIs. |
| 64 | + |
| 65 | +## Security & configuration |
| 66 | +- Secrets live in `local.properties`/env vars—never commit keys, tokens, or customer data. |
| 67 | +- Verify `config/quality/` templates before adding new env flags; integrate with Sonar only after approval. |
| 68 | +- Sanitise logs and analytics payloads; follow `SECURITY.md` for vulnerability handling. |
| 69 | + |
| 70 | +## PR & release hygiene |
| 71 | +- Target `develop`; main mirrors released artifacts. Sync with release owners before touching versioning, publishing, or changelog scripts. |
| 72 | +- Keep commits imperative (`compose: Prevent duplicate typing indicators`) and scoped. |
| 73 | +- Include test evidence in PR descriptions: Gradle task output, screenshots/screencasts for UI changes. |
| 74 | +- Run `assemble`, relevant tests, and lint tasks locally before pushing. Update documentation alongside feature toggles. |
| 75 | + |
| 76 | +### Quick checklist for agents |
| 77 | +- [ ] Confirm the module(s) touched and run their focused Gradle tasks. |
| 78 | +- [ ] Maintain binary/API compatibility; document any intentional breakage. |
| 79 | +- [ ] Honour offline/state invariants—cover edge cases like retries, reconnections, and message dedupe. |
| 80 | +- [ ] Keep Compose/XML parity when modifying shared UI behaviour. |
| 81 | +- [ ] Run Spotless and Detekt before finishing. |
| 82 | +- [ ] Add/refresh unit, UI, or snapshot tests for new behaviour. |
| 83 | +- [ ] Update changelog/deprecation docs for user-visible changes. |
| 84 | +- [ ] Scrub logs/configs for secrets before committing. |
0 commit comments