Release Instructions

Some assumptions:

master is the default branch and is production-ready
commits made to master are built and pass in buddybuild
production is our public release branch and may not match master
ideally, production will perfectly reproduce master
but if master is in an un-releasable state, we cherry-pick commits to this branch
this is an exception rather than the preferred maintenance method
all master and production builds are sent to App Store Connect, with the same buddybuild build number
App Store Connect has "internal" testers (mobile devs, product integrity)
thus, App Store Connect and TestFlight can have "external" testers which we add manually
currently, no plans exist for "external" users to include anyone outside of Mozilla

Distributing Builds through buddybuild (branch / release)

all commits on all branches and pull requests are automatically built

Push to the git branch available on GitHub.com and open a pull request
Open buddybuild from a mobile device and browse to the build
Alternatively, add an email address to the "Deployments" email list(s)
this is expected to be a small group of contributors and Mozillians

Preparing a Release (for TestFlight or App Store)

Update the release notes under docs/release-notes.md
create a pull request to collaborate and get approval
determine the next build number and include it in release notes
merge the release notes to master branch
this will result in a release build matching the build number provided
Create and merge a pull request from master to production so it tracks the release
https://github.com/mozilla-lockwise/lockwise-ios/compare/production...master
Create a tag from production matching the format: major.minor.patch.build
for example: 1.2.1399 is major version 1.2, (buddybuild) build 1399
for example: 1.3.1.1624 is major version 1.3 with 1 patch release, (buddybuild) build 1624
push the tag to GitHub and create a corresponding "Release" on GitHub.com
copy the release notes to the "Release" on GitHub
download the .ipa from buddybuild and attach it to the Release on GitHub
Hopefully by now the build has been uploaded to App Store Connect
Browse to App Store Connect and continue the "Distributing..." instructions
Download and unzip dSYM build artifact from buddybuild
Upload dSYM files to Sentry using sentry-cli using sentry instructions
HINT: if you get a 411 "content-length" error, you may need to add the --no-reprocessing flag due to a bug with GCP and the sentry-cli

In Case of Emergency (Release)

similar to above, but requires explicit cherry-pick commits on production branch when master branch is not in a release-able state

Merge the emergency changes or fixes or features to default master branch as usual
Update the release notes
Create and merge a pull request up to and including the last release-able commit on master to production
Then git cherry-pick each additional commit from master to be included in the release
thus skipping or avoiding the non-release-able commits
Push the resulting production branch to GitHub.com
Create a tag from production matching the format: major.minor.patch.build
for example: git tag -a -s 1.3.1.1624 -m "1.3.1 (Build 1624)"
Push the tag to GitHub and create a corresponding "Release" on GitHub.com
copy the release notes to the "Release" on GitHub
Browse to buddybuild and find the desired production branch build to distribute
download the .ipa from buddybuild and attach it to the Release on GitHub
From the buddybuild's build "Deploy" tab, select the "Upload to App Store Connect" link
Browse to App Store Connect to find the build and continue the "Distributing..." instructions

While most reviews are performed and completed within 24 hours, to request an expedited review request you can submit a request directly to Apple.

Distributing Builds through TestFlight (release)

all master and production branch builds are automatically uploaded from buddybuild to App Store Connect.

NOTE: if for some reason buddybuild does not deploy a build to App Store Connect, download the full App Store Connect .ipa from buddybuild and use the "Application Loader" app to manually upload it yourself.

Browse to TestFlight > Builds > iOS in App Store Connect
Find the desired build number to distribute
Provide export compliance responses

Does your app use encryption? Select Yes even if your app only uses the standard encryption in iOS and macOS.

Yes

Does your app qualify for any of the exemptions provided in Category 5, Part 2 of the U.S. Export Administration Regulations?

Yes (c) Limited to authentication, digital signature, or the decryption of data or files

Once provided, this makes the build immediately available to "internal" App Store Connect users
Copy the release notes for this release and add them to the "Test Details"
Add at least one other "Group" of "external" testers to the build
after review, this will make it available for all those "external" testers
example: "lockbox-dev" which includes our other non-App Store Connect engineers
example: "Product" which includes other product and content Mozillians
example: "Cohort A" which includes the first round of volunteers to test

Distributing through the App Store (release)

Currently all the mobile engineering managers and release management team members (see private #release-coordination channel in Mozilla Slack) both have access to distribute production releases through the App Store.

Browse to the App Store section in App Store Connect
Confirm the "App Information" details are accurate and complete
Confirm the "Pricing and Availability" details are accurate and complete
Browse to the "iOS App" section to "Prepare for Submission"
provide the version information (keywords, URLs, promotional screenshots)
select the corresponding build number for the App Store release
set the release instructions (manually, immediately, on a date)
NOTE: the best practice is to opt for the "Phased" release which starts at 1% per day, then 2% up to 100% after 7 days. This way you can "Pause" the release if early use results in new findings or big issues. The app will still be available to users who manually access the App Store "Update" section, though.
Save and "Submit for Review"

NOTE: brand new apps may take up to 2 or more hours to appear throughout the App Store whereas existing app (updates) can appear within an hour. Schedule accordingly!

Taking screenshots for new releases

Screenshots are automated via Fastlane. To get Fastlane, run brew cask install fastlane. From there, you will be able to run fastlane snapshot in the root directory of the project to run the screenshot task.

Configuration: - [languages] Update / add desired locales to fastlane/Snapfile - [devices] Update / add desired device sizes to fastlane/Snapfile - text size Update the CONTENT_SIZE variable in LockboxXCUITests/BaseTestCase.swift

Preparation before and after a release

Before testing or distributing a release: make sure the release number is still what you want and expect it to be, especially if major (versus minor) changes were made. (see below on how to "change the version").
Once development is complete: consider running the string export script to send new and updated strings to Pontoon for localization (see localization.md)
Before public release: consider running the string import script to get the latest from Pontoon (see localization.md)
After public release: consider filing an issue for the next sprint/release to update to the latest dependencies (application-services, for example)
After public release: consider running mkdocs gh-deploy so the latest docs are also published to the GitHub pages website
After public release: change the version to a major or minor update depending on the future plans.
Update the value in Common/Resources/Info.plist for the Lockbox app, for example from 1.2 to 1.3
Also update the value in CredentialProvider/Info.plist for the extension to the exact same version
After public release: make sure the dSYMs were uploaded to Sentry as part of the process earlier, do it now if not so your error reports are symbolicated.
After changing the version: TestFlight requires manual Beta review before any build is distributed. Be sure to submit a new build to TestFlight Beta App Review as early as possible so that review doesn't prevent user testing.