Require map SDK v5.9.0 in v0.40.x

[1ec5]

v0.40.0 will become uninstallable as soon as map SDK v5.10.0 is released. We will need to release a navigation SDK v0.40.1 that requires map SDK v5.9.0 and no other version of the map SDK.

Problem

mapbox/mapbox-gl-native-ios#326 migrated the map SDK to a new download location that requires the developer to supply a Mapbox access token through HTTP basic authentication. Unfortunately, this backwards-incompatible change – arguably the most backwards-incompatible in the map SDK’s history – is being versioned as a minor release, v5.10.0, instead of as a major release, v6.0.0.

Impact

Any existing applications that have installed map SDK v5.x, whether directly or indirectly through the navigation SDK, will suddenly fail to install as soon as the developer runs pod update or carthage update. Some developers may be able to manually work around the failure by pinning their map SDK dependency to = 5.9.0 in CocoaPods or == 5.9.0 in Carthage, but this is not a discoverable option if the developer is consuming the map SDK through the navigation SDK. They can alternatively obtain and configure their access token, but neither the package manager’s error message nor the published v0.40.0 documentation makes that option discoverable either.

Some developers opt not to check in their Podfile.lock or Cartfile.resolved; this change will immediately break even a routine pod install or carthage bootstrap, both on CI and locally, until they manually downgrade the map SDK or carry out the manual step to obtain and configure their access token.

This is the third time in a little over a year that the map SDK has departed from the Semantic Versioning standard in this way, despite having been versioned above v1.0 for several years.

Mitigation

#2437 will properly upgrade navigation SDK v1.0.0-beta.2 to v5.10.0-beta.1, but that doesn’t address existing applications using ostensibly stable versions of the map and navigation SDKs.

Just like in #2143 and #2317, the navigation SDK will partially mitigate this issue by publishing a patch release of v0.40.x that pins to map SDK v5.9.0 without allowing it to upgrade any further. From that point on, it will be incompatible with any v5.9.1 patch release, no matter how critical. v0.40.1 may or may not automatically mitigate the problem for navigation SDK clients depending on their configuration:

• If CocoaPods or Carthage is configured to install navigation SDK ~> 0.40 or ~> 0.40.0, then it will automatically install v0.40.1.
• If CocoaPods is configured to install navigation SDK = 0.40.0 or = 0.40, then it will not automatically install v0.40.1 and the project will continue to be broken.
• If Carthage is configured to install navigation SDK == 0.40.0 or == 0.40, then it will not automatically install v0.40.1 and the project will continue to be broken.

v0.38.3 and v0.39.1 are unaffected by this issue because these releases require map SDK v5.5.0 specifically as a workaround for the map SDK’s last backwards-incompatible change: #2299.

/cc @mapbox/navigation-ios @mapbox/maps-ios @asinghal22 @yhahn

[zugaldia]

cc: @chloekraw @knov

[knov]

The upcoming release of the Maps SDK does not have any breaking API changes. However, you have identified a specific use case where the change in distribution is more impactful for Nav SDK users since the Maps SDK version is controlled by the Nav SDK behind the scenes.

The best option to prevent any impact and to ensure you are able to use future releases of the Maps SDK is to create a Mapbox Account downloads token (see mapbox/mapbox-gl-native-ios#326).

We will consider this prior to the stable release and appreciate you flagging this during our beta cycle.

@1ec5 Is it possible for developers to specify or pin the version of the Maps SDK they want to use and override the Nav SDK settings? (Understanding that this would still break until an update to the dependency management config is updated).

[1ec5]

Is it possible for developers to specify or pin the version of the Maps SDK they want to use and override the Nav SDK settings? (Understanding that this would still break until an update to the dependency management config is updated).

Yes, in theory, some developers may be able to manually work around the failure by pinning their map SDK dependency to = 5.9.0 in CocoaPods or == 5.9.0 in Carthage, though I’d want to test this approach to be sure. It isn’t a particularly discoverable option if the developer is consuming the map SDK through the navigation SDK.

[zugaldia]

Some developers may be able to manually work around the failure by pinning their map SDK dependency to = 5.9.0 in CocoaPods or == 5.9.0 in Carthage.

How about the reverse: why don't we (Nav SDK) pin a specific Maps SDK version number (i.e. 5.9.0 in the example above) and leave it up to the developer to manually override that Maps SDK version with another one of their preference if they choose to? This would make us consistent with Android, where dependencies are fully specified.

[1ec5]

How about the reverse: why don't we (Nav SDK) pin a specific Maps SDK version number (i.e. 5.9.0 in the example above) and leave it up to the developer to manually override that Maps SDK version with another one of their preference if they choose to? This would make us consistent with Android, where dependencies are fully specified.

CocoaPods recommends using the tadpole operator whenever possible as opposed to pinning to a specific version. This preference is clearly reflected in the pods available on CocoaPods trunk:

Operator	Number of pods
At least one ~>	238 (33%)
At least one =	98 (13%)
Mixture of ~> and =	67 (9%)
At least one >=	0
Total	728

I compiled these statistics by running the following commands, which require jq:

cd ~/.cocoapods/repos/trunk/Specs
find . -name '*.podspec.json' -exec jq '.dependencies? | add? | {"~>": (map(select(startswith("~>"))) | length), ">=": (map(select(startswith(">="))) | length), "=": (map(select(test("^[0-9]"))) | length)}? | (.["~>"] > 0 and .["="] > 0) or empty' {} \; | wc -l
# etc.

For expediency, I searched across all pods ever pushed to trunk, but only in one shard of the repository. This approach likely overrepresents usage of =, since ~> has only become more preferred over time. For a sense of perspective, 110 pods support iOS 7 or below:

find . -name '*.podspec.json' -exec jq '.platforms.ios? | test("^[1-7]\\.")? or empty' {} \; | wc -l

These statistics don’t indicate the prevalence of ~> among Podfiles, but I think they illustrate how unusual it would be for us to follow the Android navigation SDK’s approach on iOS.

[1ec5]

By way of an update, the iOS map SDK will be released as v6.0.0, eliminating the need for a v0.40.1 patch release. This issue is no longer relevant, other than the demonstration of how to gather statistics about public pods in #2447 (comment). 🌲