RoadMap

[jingjing2222]

RoadMap

This is a curated roadmap, not a dump of every upstream request.

We reviewed open issues from:

• @react-native-community/geolocation
• react-native-geolocation-service

v1.5 - selected backward-compatible work

1. Location Doctor / readiness API

• Add diagnoseLocation() or getLocationReadiness()
• Read-only diagnosis for permission, provider, services, settings, cache, and Play Services state.
• Return remediation codes. Do not change existing errors or permission prompts.
• Source issues: community #120, #251, #303, #353, service #253, #329, #393

2. Detailed permission state API

• Add getPermissionDetails()
• Keep checkPermission() unchanged.
• Report detailed scope/accuracy/can-ask-again/settings guidance where the platform exposes it.
• Source issues: community #364, #348, #335, #166, #125, service #359, #224, #236, #185

3. Detailed Android settings resolution

• Add requestLocationSettingsDetailed()
• Keep existing requestLocationSettings(): Promise<LocationProviderStatus> unchanged.
• Detailed result may distinguish satisfied, cancelled, unavailable, activityMissing, etc.
• Source issues: community #353, #251, service #250, #329, #393

4. Cancellable current-position request

• Add optional cancellation support, for example { signal }.
• Existing getCurrentPosition(options) behavior must remain unchanged.
• Source issues: community #349, #141, service #127, #227

5. Provider status watcher

• Add watchProviderStatus() or onProviderChange()
• This is observation only in v1.5.
• Do not add default automatic recovery or hidden provider switching.
• Source issues: community #303, #251, #308, service #250, #410, #418

6. Background reliability contract

• Add docs, E2E matrix, and optional status fields such as reason or lastDeliveryAt.
• Clarify foreground/background/killed/reboot/iOS suspend behavior.
• Do not change foreground-service, Headless JS, storage, boot, or persistence defaults in v1.5.
• Source issues: community #346, #314, #285, #255, #179, service #407, #404, #403, #392, #109, #102

7. iOS pause/resume lifecycle listener

• Add a separate listener such as onLocationLifecycleChange().
• Do not inject new event types into the existing background event stream by default in v1.5.
• Source issues: community #282, #281, #314, service #404, #392

8. Watch observability, not Watch Manager defaults

• Add getActiveWatches()
• Document current native merge policy and cleanup semantics.
• Do not change watch filtering, merge policy, or option-change restart defaults in v1.5.
• Source issues: community #361, #112, #111, service #419, #425, #234, #233, #309

9. Location quality metadata

• Add optional response metadata such as source, age, quality, staleReason.
• Do not reject stale or low-accuracy locations by default in v1.5.
• Source issues: community #35, #61, #355, service #307, #168, #174, #421, #439

10. Mock / integrity metadata polish

• Improve Modern API metadata docs/tests.
• Consider opt-in compat metadata only if it does not weaken drop-in compatibility.
• Do not change compat response shape by default in v1.5.
• Source issues: community #359, #287, service #446, #411, #257

11. Recipes and verification kit

• Add GPS-only / offline recipe and E2E/manual matrix.
• Add consumer E2E contract kit.
• Add compatibility matrix.
• Keep this as docs/templates/helpers, not hidden runtime policy.
• Source issues: community #347, #298, #295, service #379, #142, #136, #296, #345, #407

12. Install doctor and Expo opt-in plugin

• Add nitro-geolocation doctor
• Add an opt-in Expo config plugin.
• No postinstall.
• No automatic native config mutation.
• Source issues: community #362, #360, #350, #345, #324, #296, #221, service #451, #448, #442, #441, #420

13. Privacy / compliance documentation

• Add privacy statement, dependency disclosure, SBOM/license notes, and scanner guidance.
• No automatic telemetry.
• Source issues: community #161, #309, service #353, #435, #447

v2.0 - selected breaking work

Existing v2 BC items

• Remove ModernGeolocationConfiguration alias

  • It duplicates GeolocationConfiguration.

• Remove enableHighAccuracy from the Modern API

  • accuracy is not deprecated; it is the v1.2+ replacement for enableHighAccuracy.
  • enableHighAccuracy is deprecated in the Modern API, kept only for v1 compatibility, and expected to be removed from the Modern API in v2.
  • Keep enableHighAccuracy in /compat for @react-native-community/geolocation drop-in compatibility.

• Change last-known position API

  Before:

  getLastKnownPosition(
    options?: LocationRequestOptions
  ): Promise<GeolocationResponse | undefined>

  After:

  getLastKnownPosition(): GeolocationResponse | undefined
  
  getLastKnownPositionAsync(
    options?: LocationRequestOptions
  ): Promise<GeolocationResponse | undefined>

  Reason:

  • sync: return module cache only
  • async: may query platform/GMS cached sources
  • both: cached-only, no fresh location request

Additional selected v2 candidates

• Replace requestLocationSettings() with a deterministic result object

  • Current API resolves LocationProviderStatus.
  • Source issues: community #353, #251, service #250, #329, #393

• Make Watch Manager v2 semantics the default, if v1.5 observability proves the behavior

  • Source issues: community #361, #112, service #419, #425, #234

• Integrate lifecycle/provider events into the unified background event stream, if the unified event model is worth the BC break

  • Source issues: community #282, #281, service #404, #392

• Rework error taxonomy only with a migration guide