How to Build an iOS Release Candidate for SimplyE and Open eBooks

For releasing we follow the standard Git Flow method of branching.

Building and Distributing

Our CI takes care of building SimplyE and Open eBooks and pushing them to both Firebase and -- for release builds -- TestFlight. There are still a few manual steps and assumptions we need to consider though.

As an example, let's assume we're releasing version SimplyE 3.6.0. For Open eBooks, an identical flow applies: just replace "SimplyE" with "Open eBooks".

1. In order for our CI to upload a build to TestFlight, it will need a valid Apple login session, which we create via Fastlane. However, since this login session expires after 1 month, it might be a good idea to check and refresh it if it has been that long. You can verify how long it has been from the Simplified-iOS Settings/Secrets tab.
2. Clone the official Simplified-iOS repo if you haven't already.
3. For a regular release, checkout develop, per Git Flow.
   • For a hotfix release, checkout master instead (also per Git Flow)
4. Create a new release branch with the following format: git checkout -b release/[simplye|openebooks]/3.6.0. Push the branch upstream. Since we did not increase the build number, the version check step in the main GitHub Action "SE / OE build" workflow should abort the actual build.
5. Bump the build number: e.g. if you had 3.6.0 (10) on develop, bump it to 11 on the release branch and push a new commit there. This should now trigger the same workflow but this time the version check step should pass, and the action should kick off an actual build. Verify that this happens.
6. Bump the patch version number on develop. In this example since we are in the process of releasing 3.6.0, develop should be set to 3.6.1. We should do this right away to avoid confusion in build distribution. In fact, QA engineers will receive 3.6.0 (n) builds (obviously), but could also receive builds related to work intended for the next release, so a different version is necessary to distinguish between builds. Make sure to explain this in the Firebase release notes for these develop / 3.6.1 builds.
7. Once the build completes successfully (this may take 30+ minutes) you should be able to see it on Firebase and TestFlight. Note that TestFlight will require additional time for "processing" the build.
8. Once the TestFlight build is available, add internal release notes to it in App Store Connect. Submit the build to Apple for Beta Review. This is a one-time thing we should do for every release. It usually takes a day for Apple to beta-review. This will allow us to be ready to send the build to external testers during the QA cycle, if/when we need to.
9. All of our QA and Product people should automatically receive the TestFlight build even without beta-review approval from Apple. However, because TestFlight can be flaky, it's worth checking at least with the QA team whether they got the build or not, since they will have to do regression testing on it. Worst case, use Firebase if you can't manage to deliver from TestFlight.

After Distributing

Per Git Flow process, if a regression is found during QA, fix it on the release branch.

After Releasing to the App Store

After the build is shipped there's some bookkeeping we need to do on GitHub:

1. open PR on NYPL-Simplified/Simplified-iOS to merge the Release branch to develop. If no regressions were found, this might not be necessary.
2. open PR on NYPL-Simplified/Simplified-iOS to merge the Release branch to master.
3. After both PRs are merged, remove the release branch from local and remote repos.
4. Then and only then, tag the release at top of master:

    # for SimplyE:
    $ git tag -a simplye-v3.6.0 <COMMIT-HASH-TOP-OF-MASTER>

    # for Open eBooks:
    $ git tag -a openebooks-v3.6.0 <COMMIT-HASH-TOP-OF-MASTER>

    $ git push --follow-tags ## to NYPL’s remote

5. On https://github.com/NYPL-Simplified/Simplified-iOS/releases click the last tag you just pushed, then “Edit tag”
6. Add title ("SimplyE v3.6.0" / "Open eBooks v3.6.0") and description (the release notes you entered in git tag) and hit Publish.