AGENTS.md

1# Repository Guidelines
2 
3## Project Structure & Module Organization
4This is a Kotlin Multiplatform monorepo built with Gradle. Public library modules live at the repository root (for example `coil-core`, `coil-compose`, `coil-network-okhttp`, `coil-gif`, `coil-svg`, `coil-video`, `coil-test`, `coil-bom`). Internal tooling and test support modules are under `internal/`, and runnable examples are under `samples/` (`samples:compose`, `samples:compose-android`, `samples:view`).
5 
6Most modules use source sets like `src/commonMain`, `src/commonTest`, `src/androidMain`, `src/androidUnitTest`, and `src/androidInstrumentedTest`. Documentation content lives in `docs/`.
7 
8## Build, Test, and Development Commands
9- `./gradlew spotlessCheck`: run Kotlin formatting/lint checks.
10- `./gradlew lint`: run Android lint checks.
11- `./gradlew checkKotlinAbi`: verify public API compatibility.
12- `./gradlew updateKotlinAbi`: refresh ABI baselines when API changes are intentional.
13- `./test.sh`: full local validation used by maintainers (style + unit/instrumentation/screenshot tests).
14- `./gradlew allTests testDebugUnitTest`: run core unit tests quickly.
15- `./gradlew connectedDebugAndroidTest`: run Android instrumentation tests (emulator/device required).
16 
17## Coding Style & Naming Conventions
18Follow `.editorconfig`: UTF-8, LF endings, 4-space indentation, max line length 100, final newline, no trailing whitespace. Kotlin formatting is enforced via Spotless + ktlint (`intellij_idea` style with project-specific rule overrides).
19 
20Match existing naming patterns: packages under `coil3.*`, types in `UpperCamelCase`, members in `lowerCamelCase`, constants in `UPPER_SNAKE_CASE`. Keep file names aligned with primary types (for example `NetworkFetcher.kt`).
21 
22## Testing Guidelines
23Tests use Kotlin Test/JUnit, Robolectric, Android instrumentation, and screenshot tooling (Paparazzi/Roborazzi/Compose screenshot validation). Name test files `*Test.kt` and place them in the appropriate source set (`commonTest`, `androidUnitTest`, etc.).
24 
25For bug fixes, add or update a failing test first when possible. Run `./test.sh` before opening a PR.
26 
27## Commit & Pull Request Guidelines
28Use concise, imperative commit subjects (for example `Fix macOS test flakiness`). Dependency updates commonly use Conventional Commit style (for example `fix(deps): ...` or `chore(deps): ...`).
29 
30PRs should include:
31- A clear summary of what changed and why.
32- Linked issue(s) when applicable.
33- Test evidence (commands run, and screenshots for UI/screenshot test changes).
34- Updated ABI files when public API changes are intentional.
35- Add the following text at the end of the last line of the PR description: `review-path-agent`.
36 
37Before submitting, ensure `./test.sh` passes locally.
38