docs: clarify that Position.heading carries course over ground (#1187)#1783
Merged
mvanbeusekom merged 1 commit intoJun 8, 2026
Merged
Conversation
…low#1187) Position.heading is named "heading" but actually carries course over ground (direction of travel), not compass heading. Update the dartdoc to explain this; keep the heading name for backward compatibility. The value comes from Location.getBearing() on Android and CLLocation.course on iOS. Bump geolocator_platform_interface to 4.2.7 and add a CHANGELOG entry, as requested by the maintainer in Baseflow#1187.
mvanbeusekom
approved these changes
Jun 8, 2026
mvanbeusekom
left a comment
mvanbeusekom
left a comment
Member
There was a problem hiding this comment.
This is awesome, thank you so much!
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Resolves #1187.
As discussed in #1187,
Position.headingis named "heading" but actually carries course over ground (the direction of travel), not compass heading. In the issue, @mvanbeusekom proposed a documentation clarification rather than a breaking rename, and invited a PR.This updates the dartdoc of
Position.headingingeolocator_platform_interfaceto explain that the value is course over ground (distinct from compass heading), and that theheadingname is retained for backward compatibility.The documented native sources are accurate:
geolocator_android/.../LocationMapper.javamapsheadingfromLocation.getBearing().geolocator_apple/.../LocationMapper.mmapsheadingfromCLLocation.course.This is documentation-only — no code, signature, or serialization changes; the
headingfield name and behaviour are unchanged, so it is non-breaking.Per your request in the issue:
geolocator_platform_interface4.2.6→4.2.7.## 4.2.7CHANGELOG entry. I left the existing## NEXTflutter_lints ^5.0.0entry underNEXTso you can cut that on your own cadence — happy to fold it into this release instead if you'd prefer.Verification (
geolocator_platform_interface, Flutter 3.45 / Dart 3.11):dart format— clean (no changes)flutter analyze— No issues found!flutter test— All tests passed! (115/115)Branched from
mainper your note that the repo no longer uses adevelopbranch.