releases.md

🚨 As of January 2021 the release process has been simplified to make maintenance mode simpler. Releases are still created from master, but instead of the process describes below, we simply create a releases_v1.8.0 branch on which all 1.8.x releases can be made. Commits for the 1.8.x release can land directly or be uplifted to that branch. When a release needs to be made, create a dot release (including the initial 1.8.0 through the GitHub release UI. BuddyBuild still builds these and the build that was tagged can be uploaded to App Store Connect. Contact @st3fan for more details.

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

1. Push to the git branch available on github.com and open a pull request
2. Open buddybuild from a mobile device and browse to the build
3. 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)

1. 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

2. 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

3. 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

4. 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

5. Hopefully by now the build has been uploaded to App Store Connect
6. Browse to App Store Connect and continue the "Distributing..." instructions
7. Download and unzip dSYM build artifact from buddybuild
8. 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

1. Merge the emergency changes or fixes or features to default master branch as usual
2. Update the release notes
3. Create and merge a pull request up to and including the last release-able commit on master to production
4. Then git cherry-pick each additional commit from master to be included in the release

• thus skipping or avoiding the non-release-able commits

5. Push the resulting production branch to github.com
6. 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)"

7. Push the tag to GitHub and create a corresponding "Release" on github.com

• copy the release notes to the "Release" on GitHub

8. 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

9. From the buddybuild's build "Deploy" tab, select the "Upload to App Store Connect" link
10. 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.

1. Browse to TestFlight > Builds > iOS in App Store Connect
2. Find the desired build number to distribute
3. 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

4. Once provided, this makes the build immediately available to "internal" App Store Connect users
5. Copy the release notes for this release and add them to the "Test Details"
6. 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.

1. Browse to the App Store section in App Store Connect
2. Confirm the "App Information" details are accurate and complete
3. Confirm the "Pricing and Availability" details are accurate and complete
4. 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.

5. 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.