From 7a0e23acdfb04316a379c4650e6fa8161a0d9521 Mon Sep 17 00:00:00 2001
From: Kilian Finger <finger@trafficon.eu>
Date: Tue, 17 Dec 2024 13:28:00 +0100
Subject: [PATCH] docs: add migration docs (#560)

---
 README.md                     |  8 ++--
 docs/guides/migrations/v10.md | 75 +++++++++++++++++++++++++++++++++++
 2 files changed, 80 insertions(+), 3 deletions(-)
 create mode 100644 docs/guides/migrations/v10.md

diff --git a/README.md b/README.md
index 72b3b16fd..cf1ec529c 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,8 @@ diverged, it has become necessary to separate the projects into specific wrapper
     - [Android](/docs/guides/setup/Android.md)
     - [iOS](/docs/guides/setup/iOS.md)
   - [Expo](/docs/guides/setup/Expo.md)
+- Migrations
+  - [Migrating to v10](/docs/guides/migrations/v10.md)
 
 ### Components
 
@@ -41,9 +43,9 @@ diverged, it has become necessary to separate the projects into specific wrapper
 - [PointAnnotation](/docs/components/PointAnnotation.md)
 - [MarkerView](/docs/components/MarkerView.md)
 - [Callout](/docs/components/Callout.md)
-- [Camera](docs/components/Camera.md)
-- [UserLocation](docs/components/UserLocation.md)
-- [Images](docs/components/Images.md)
+- [Camera](/docs/components/Camera.md)
+- [UserLocation](/docs/components/UserLocation.md)
+- [Images](/docs/components/Images.md)
 
 ### Sources
 
diff --git a/docs/guides/migrations/v10.md b/docs/guides/migrations/v10.md
new file mode 100644
index 000000000..459af1340
--- /dev/null
+++ b/docs/guides/migrations/v10.md
@@ -0,0 +1,75 @@
+# Migrating to v10
+
+## Changes to `Camera` Component
+
+### Default `animationMode` is now `CameraMode.None`
+
+The default `animationMode` for a controlled `Camera` is now `CameraMode.None`. To reinstate previous behavior, change the following:
+
+```diff
+<Camera
+  centerCoordinates={[0, 0]}
++  animationDuration={2000}
++  animationMode="easeTo"
+/>
+```
+
+### Removed `allowUpdates` and `triggerKey` Props
+
+If you need this functionality, keep your props stable or use the imperative `setCamera`. 
+
+```diff
+<Camera
+  centerCoordinates={[0, 0]}
+-  allowUpdates={false}
+-  triggerKey={someKey}
+/>
+```
+
+## `MapView` props `styleURL` and `styleJSON` unified to `mapStyle`
+
+The props `styleURL` and `styleJSON`, which control the style of the `MapView`, have been unified into a single `mapStyle` prop.
+
+### `styleURL`
+
+```diff
+<MapView
+-  styleURL="https://some-style-url"
++  mapStyle="https://some-style-url"
+/>
+```
+
+### `styleJSON`
+
+A style object is now expected as an object, without `JSON.stringify`.
+
+```diff
+<MapView
+-  styleJSON={JSON.stringify(someStyleObject)}
++  mapStyle={someStyleObject}
+/>
+```
+
+## Removed `Style` component
+
+The `Style` component was redundant, as it's possible to pass a style object to the `MapView` directly.
+
+```diff
+- <MapView>
+-  <Style json={someStyleObject} />
+- </MapView>
++ <MapView mapStyle={someStyleObject} />
+```
+
+## Replaced `OfflineProgressStatus` with `OfflinePackStatus`
+
+The two types have been unified. Simply replace `OfflineProgressStatus` with `OfflinePackStatus`.
+
+# Removed deprecated Methods, Props and Types
+
+- `UserTrackingModes` was removed, use `UserTrackingMode` instead
+- Removed `setCamera` from `MapView`, use imperative methods of `Camera` instead
+- Removed `byId` methods from ShapeSource
+- Removed `children` from SymbolSource
+- Removed `assets` key from `Images`
+- Removed deprecated event keys