Releasing the Mapbox macOS SDK

Congratulations, you’re the proud owner of a new release of the Mapbox Maps SDK for macOS! The process below takes 20–30 minutes, most of it babysitting the compiler.

When to release

To the extent possible, we release the Mapbox Maps SDK for macOS in tandem with the Mapbox Maps SDK for iOS, so that developers who work on both platforms can count on feature parity and the same bug fixes between the two SDKs. However, if a critical bug fix affects only macOS, we may issue an out-of-band release of the macOS SDK; conversely, we may delay the macOS SDK release if a critical issue arises in the iOS SDK.

Prepare for release

Takes under 5 minutes

1. Skim the issues tagged macOS or issues mentioning “macOS” in case there are any showstoppers.
2. Run tx pull -a to add or update translations.
3. Update the first section of the changelog to reflect any notable changes to the SDK, shared iOS/macOS code, or mbgl since the previous release. Compare the previous release tag with master or the release branch to find notable changes. Look in particular for commit messages prefixed with [macos], [ios, macos], or [core].
4. If the screenshot hasn’t been updated in awhile, compose a new version that shows off the new release’s features. Try to show styles, cities, or features that haven’t been depicted in the macOS SDK screenshot before.
5. Commit these changes and open a PR to get them reviewed and merged.

Tag the release

Takes under 5 minutes

1. Decide on a semver-compliant version number according to these guidelines. The version number should be of the form 0.9.8-alpha.1, 0.9.8-beta.1, 0.9.8-rc.1 (for a release candidate), or 0.9.8 (for a final release).
2. Run ./platform/macos/scripts/update-version.sh v0.9.8, where 0.9.8 is the semver-compliant version you chose in step 1. Commit the resulting changes with a commit message like macos-v0.9.8 and open a PR to get it reviewed and merged.
3. Tag the merged podspec changes as macos-v0.9.8, where 0.9.8 is the semver-compliant version you chose in step 1. Push the tag.

Publish the release

Takes 10–15 minutes

1. Run xcodebuild -version or xcode-select -p to make sure you’re building with the right version of Xcode.
2. If this is your first time releasing the Mapbox Maps SDK for macOS:
   1. Install wget and github-release from Homebrew and caffeinate from RubyGems.
   2. Add export GITHUB_TOKEN='8BADF00DDEADBEEFC00010FF' to your .bash_profile, where 8BADF00DDEADBEEFC00010FF is a new GitHub personal access token.
   3. Optionally, to code-sign Mapbox GL.app, you’ll need to install a provisioning profile for your Mac Developer Program membership.
3. Make sure your Mac is plugged in, then run make xdeploy. A script will build the SDK, package it up, and finally upload the package to a new GitHub release, all the while keeping your computer from falling asleep.
4. While you wait, draft a new release. Add release notes based on the release’s section in the changelog. (Unlike the changelog, release notes accept #123 syntax for linking to PRs.) Use one of these templates:
   • Release notes template
   • Prerelease notes template
5. Once the script runs to completion, it should have drafted a new GitHub release with binary packages attached. Copy the release notes you drafted above into the new release. Title the release macos-v0.9.8 (where 0.9.8 is the new version). Save the draft.
6. Check “This is a pre-release” if applicable, then click “Publish release”. Delete the other draft you made.

Update the documentation

Takes 5–10 minutes

1. Update the Mapbox Maps SDK for macOS documentation site (which is also bundled with the SDK):
   1. Clone mapbox-gl-native to a mapbox-gl-native-pages folder alongside your main mapbox-gl-native clone, and check out the gh-pages branch.
   2. In your main mapbox-gl-native clone, check out the release branch and run make xdocument STANDALONE=1 OUTPUT=../mapbox-gl-native-pages/macos/0.9.8, where 0.9.8 is the new SDK version.
   3. In mapbox-gl-native-pages, edit macos/index.html and macos/docsets/Mapbox.xml to refer to the new SDK version.
   4. In mapbox-gl-native-pages, edit macos/Mapbox-macOS-SDK.json and macos/Mapbox-macOS-SDK-symbols.json.
   5. Commit and push your changes to the gh-pages branch.
2. If any new style properties or features are supported in the new release, update the “SDK support” tables in the style specification documentation:
   1. If this is your first time updating the style specification documentation, install yarn from Homebrew.
   2. Update the sdk-support objects in v8.json. The macos key in an sdk-support object for a particular property indicates the minimum macOS SDK version that supports that property. If the sdk-support object is missing a macos key, the property is assumed to be unsupported in the macOS SDK.
   3. If the release adds support for features other than properties, update docs/style-spec/_generate/index.html.
   4. Run yarn install && yarn run build-style-spec to generate the style specification site.
   5. Commit these changes and open a PR in the mapbox-gl-js repository to get them reviewed and merged. (Keep going while you wait for a review.)
   6. Once the PR is merged, cherry-pick the changes into the mb-pages branch, so that they go live on mapbox.com ahead of the next Mapbox GL JS release.
3. Update the VERSION_MACOS_MAPS_SDK site variable in the mapbox/ios-sdk repository, or ask for help in the #gl-collab Slack channel if you don’t work for Mapbox. This variable affects links to the macOS map SDK release page in the iOS map SDK’s “Offline sideloading” tutorial.
4. Edit this table at the OpenStreetMap Wiki to correctly indicate the status of any new features.

Tell your friends!

Takes under 5 minutes

1. If this is your first time releasing the Mapbox Maps SDK for macOS:
   1. Sign up for a CocoaPods trunk account.
   2. Get one of the Mapbox-macOS-SDK pod’s owners to add you as an owner.
2. Once the documentation site finishes publishing the updates, push the podspecs to CocoaPods trunk:

   pod trunk push platform/macos/Mapbox-macOS-SDK.podspec
   pod trunk push platform/macos/Mapbox-macOS-SDK-symbols.podspec

3. Copy pod’s success message and let Mapbox’s Mobile team know about the new release by sending this message to the #mobile Slack channel if you work for Mapbox or the #gl-collab Slack channel if you don’t.
4. Submit an update to OSMBC to get a mention in the next issue of WeeklyOSM.

Whew! Now you can close the release’s milestone and create one for the next release!