Improve migration guide.

docs/upgrading_to_coil3.md

@@ -1,8 +1,5 @@
 # Upgrading to Coil 3.x
 
-!!! Note
-    The doc is a work in progress and will be improved before the final Coil 3.0 release.
-
 Coil 3 is the next major version of Coil that has a number of major improvements:
 
 - Full support for [Compose Multiplatform](https://www.jetbrains.com/lp/compose-multiplatform/). Coil supports all major targets (Android, iOS, JVM, JS, and [WASM](https://coil-kt.github.io/coil/sample/)) and works with [Compose Multiplatform Resources](https://www.jetbrains.com/help/kotlin-multiplatform-dev/compose-multiplatform-resources.html) without issue.
@@ -20,17 +17,11 @@ Coil's Maven coordinates were updated from `io.coil-kt` to `io.coil-kt.coil3` an
 
 The `coil-base` and `coil-compose-base` artifacts were renamed to `coil-core` and `coil-compose-core` respectively to align with the naming conventions used by Coroutines, Ktor, and AndroidX.
 
-## Default Changes
-
-Coil 3.0 has several import default changes:
-
-- Cache headers are no longer respected by default. See [here](network.md) for more info.
-- A file's last write timestamp is no longer added to its cache key by default. This is to avoid reading the disk on the main thread (even for a very short amount of time). This can be renabled with `ImageRequest.Builder.addLastModifiedToFileCacheKey` or `ImageLoader.Builder.addLastModifiedToFileCacheKey`.
-- Output image dimensions are now forced to be less than 4096x4096 to guard against accidental OOMs. This can be configured with `ImageLoader/ImageRequest.Builder.maxBitmapSize`.
-
 ## Network Images
 
-`coil-core` no longer supports loading images from the network by default. [**You must** add a dependency on one of Coil's network artifacts. See here for more info.](network.md). This was changed so consumers could use different networking libraries or avoid a network dependency if their app doesn't need it. 
+**`coil-core` no longer supports loading images from the network by default.** [**You must** add a dependency on one of Coil's network artifacts. See here for more info.](network.md). This was changed so consumers could use different networking libraries or avoid a network dependency if their app doesn't need it.
+
+Additionally, Cache control headers are no longer respected by default. See [here](network.md) for more info.
 
 ## Multiplatform
 
@@ -40,10 +31,10 @@ On Android, Coil uses the standard graphics classes to render images. On non-And
 
 As part of decoupling from the Android SDK, a number of API changes were made. Notably:
 
-- `Drawable` was replaced with a custom `Image` interface. Use `Drawable.asImage()` and `Image.asDrawable()` to convert between the classes on Android. On non-Android platforms use `Bitmap.asImage()` and `Image.toBitmap()`. You can also write your own subclasses, though that's more advanced.
-- Android's `android.net.Uri` class was replaced a multiplatform `coil3.Uri` class. Any instances of `android.net.Uri` that are used as `ImageRequest.data` will be mapped to `coil3.Uri` before being fetched/decoded.
+- `Drawable` was replaced with a custom `Image` interface. Use `Drawable.asImage()` and `Image.asDrawable()` to convert between the classes on Android. On non-Android platforms use `Bitmap.asImage()` and `Image.toBitmap()`.
+- Android's `android.net.Uri` class was replaced a multiplatform `coil3.Uri` class. Any instances of `android.net.Uri` that are used as `ImageRequest.data` will be mapped to `coil3.Uri` before being fetched/decoded. Custom `Fetcher`s that relied on this will need to be updated to use `coil3.Uri`.
 - Usages of `Context` were replaced with `PlatformContext`. `PlatformContext` is a type alias for `Context` on Android and can be accessed using `PlatformContext.INSTANCE` on non-Android platforms. Use `LocalPlatformContext.current` to get a reference in Compose Multiplatform.
-- The `Coil` class was renamed to `SingletonImageLoader`. 
+- The `Coil` class was renamed to `SingletonImageLoader`.
 - If you're implementing `ImageLoaderFactory` in your custom Android `Application` class, you'll need to switch to implementing `SingletonImageLoader.Factory` as a replacement for `ImageLoaderFactory`. Once you implement `SingletonImageLoader.Factory`, you'll be able to override `newImageLoader()` if you need or want to override it.
 
 The `coil-svg` is supported in multiplatform, but the `coil-gif` and `coil-video` artifacts continue to be Android-only (for now) as they rely on specific Android decoders and libraries.
@@ -52,9 +43,18 @@ The `coil-svg` is supported in multiplatform, but the `coil-gif` and `coil-video
 
 The `coil-compose` artifact's APIs are mostly unchanged. You can continue using `AsyncImage`, `SubcomposeAsyncImage`, and `rememberAsyncImagePainter` the same way as with Coil 2.x. Additionally, this methods have been updated to be [restartable and skippable](https://developer.android.com/jetpack/compose/performance/stability) which should improve their performance.
 
+- `AsyncImagePainter.state` is now a `StateFlow`. It should be observed like so: `painter.state.collectAsState()`.
+- `AsyncImagePainter`'s default `SizeResolver` no longer waits for the first `onDraw` call to get the size of the canvas. Instead, `AsyncImagePainter` defaults to `Size.ORIGINAL`.
+- The Compose `modelEqualityDelegate` delegate is now set via a composition local, `LocalAsyncImageModelEqualityDelegate`, instead of as a parameter to `AsyncImage`/`SubcomposeAsyncImage`/`rememberAsyncImagePainter`.
+
 !!! Note
     If you use Coil on a JVM (non-Android) platform, you should add a dependency on a [coroutines main dispatcher](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-dispatchers/-main.html). On desktop you likely want to import `org.jetbrains.kotlinx:kotlinx-coroutines-swing`. If it's not imported then `ImageRequest`s won't be dispatched immediately and will have one frame of delay before setting the `ImageRequest.placeholder` or resolving from the memory cache.
 
-## Extras
+## General
 
-Coil 2's `Parameters` API was replaced by `Extras`. `Extras` don't require a string key and instead rely on identity equality. `Extras` don't support modifying the memory cache key. Instead, use `ImageRequest.memoryCacheKeyExtra` if your extra affects the memory cache key.
+Other import behavior changes include:
+
+- Remove support for `android.resource://example.package.name/drawable/image` URIs as it prevents resource shrinking optimizations. If you still needs its functionality you can [manually include `ResourceUriMapper` in your component registry](https://github.com/coil-kt/coil/blob/main/coil-core/src/androidInstrumentedTest/kotlin/coil3/map/ResourceUriMapper.kt).
+- A file's last write timestamp is no longer added to its cache key by default. This is to avoid reading the disk on the main thread (even for a very short amount of time). This can be re-enabled with `ImageRequest.Builder.addLastModifiedToFileCacheKey(true)` or `ImageLoader.Builder.addLastModifiedToFileCacheKey(true)`.
+- Output image dimensions are now forced to be less than 4096x4096 to guard against accidental OOMs. This can be configured with `ImageLoader/ImageRequest.Builder.maxBitmapSize`.
+- Coil 2's `Parameters` API was replaced by `Extras`. `Extras` don't require a string key and instead rely on identity equality. `Extras` don't support modifying the memory cache key. Instead, use `ImageRequest.memoryCacheKeyExtra` if your extra affects the memory cache key.