From 9cfa0afd115e9e6c3c7c97ca2241794d6e387382 Mon Sep 17 00:00:00 2001
From: m0nac0 <58807793+m0nac0@users.noreply.github.com>
Date: Fri, 30 Jun 2023 13:28:02 +0200
Subject: [PATCH] Document breaking change from #244 (#247)

depends on #244

---------

Co-authored-by: Julian Bissekkou <36447137+JulianBissekkou@users.noreply.github.com>
---
 CHANGELOG.md                                   | 11 +++++++++++
 lib/src/mapbox_map.dart                        |  4 +++-
 maplibre_gl_platform_interface/lib/src/ui.dart |  7 ++++++-
 3 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a28258944..db3c85728 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,14 @@
+## upcoming version
+
+### Breaking Change:
+* The default for `myLocationRenderMode` was changed from `COMPASS` to `NORMAL` in https://github.com/maplibre/flutter-maplibre-gl/pull/244, since the previous default value of `COMPASS` implicitly enables displaying the location on iOS, which could crash apps that didn't want to display the device location. If you want to continue to use `MyLocationRenderMode.COMPASS`, please explicitly specify it in the constructor like this:
+```dart
+MaplibreMap(
+ myLocationRenderMode: MyLocationRenderMode.COMPASS,
+ ...
+)
+```
+
 ## 0.16.0, Jun 28, 2022
 * cherry-picked all commits from upstream up to [https://github.com/flutter-mapbox-gl/maps/commit/3496907955cd4b442e4eb905d67e8d46692174f1), including up to release 0.16.0 from upstream
 * updated Maplibre GL JS for web
diff --git a/lib/src/mapbox_map.dart b/lib/src/mapbox_map.dart
index 4a396d2e9..01e3764f4 100644
--- a/lib/src/mapbox_map.dart
+++ b/lib/src/mapbox_map.dart
@@ -163,7 +163,9 @@ class MaplibreMap extends StatefulWidget {
   /// `myLocationEnabled` needs to be true for values other than `MyLocationTrackingMode.None` to work.
   final MyLocationTrackingMode myLocationTrackingMode;
 
-  /// The mode to render the user location symbol
+  /// Specifies if and how the user's heading/bearing is rendered in the user location indicator.
+  /// See the documentation of [MyLocationRenderMode] for details.
+  /// If this is set to a value other than [MyLocationRenderMode.NORMAL], [myLocationEnabled] needs to be true.
   final MyLocationRenderMode myLocationRenderMode;
 
   /// Set the layout margins for the Mapbox Logo
diff --git a/maplibre_gl_platform_interface/lib/src/ui.dart b/maplibre_gl_platform_interface/lib/src/ui.dart
index d24723f42..f8036fb03 100644
--- a/maplibre_gl_platform_interface/lib/src/ui.dart
+++ b/maplibre_gl_platform_interface/lib/src/ui.dart
@@ -17,10 +17,15 @@ enum MyLocationTrackingMode {
   TrackingGPS,
 }
 
-/// Render mode
+/// Specifies if and how the user's heading/bearing is rendered in the user location indicator.
 enum MyLocationRenderMode {
+  /// Do not show the user's heading/bearing.
   NORMAL,
+
+  /// Show the user's heading/bearing as determined by the device's compass. On iOS, this causes the user's location to be shown on the map.
   COMPASS,
+
+  /// Show the user's heading/bearing as determined by the device's GPS sensor. Not supported on iOS.
   GPS,
 }