← iOS

Making Swift Package Releases

Basics

There are several things to understand first:

  • The branch called main always has the source for the most recent release of the package.
  • The branch called develop is where changes are made as we work toward the next release.
  • When making a release, a branch is created from develop to merge to main. After that branch is merged, the release tag is applied to the merge commit on main. In some cases, main is then merged back to develop.

Version Considerations

When choosing the version of the next release, please consider the following:

  • If the release contains only bug fixes, then the host app should be able to use the new version without code changes. In this case, the patch version can be incremented. For example, that would be the case of going from 1.3.0 to 1.3.1.
  • If the release only adds features without changing public interfaces, then the host app should be able to use the new version without code changes. Taking advantage of new features from the SDK should not break the host app. In this case, the minor version can be incremented. For example, that would be the case of going from 1.3.0 to 1.4.0.
  • If the release has public breaking changes of any kind, then the major version must be incremented. For example, that would be the case of going from 1.3.0 to 2.0.0.

IMPORTANT: The Banno Mobile app is configured to use package versions up to the next major release for our internal packages. Hence, it is vital that the risk and the impact of an update be considered when choosing the version number. A package-level change may not alter anything but internal details, but that could still cause a regression. Moreover, app builds go out all month long, not just in one big batch after a release is finalized. Package changes tagged as a patch or a minor release will be picked up by any and all app builds made after the tag is laid down on the package repository.

If you are unsure, then it may be necessary to get feedback. If all else fails, update the major version number.

Releasing a New Version

For the purposes of these instructions, the version to be release will be called 1.3.1. The assumption here is that develop is in a place where a release is ready to be tagged and deployed.

There are several steps to perform. Please follow them closely.

  1. Create a branch called release/1.3.1 relative to the current state of develop.
  2. Open a PR that will merge release/1.3.1 to main.
  3. After the PR has been merged to main, then apply the tag to the merge commit on main:
git switch main
git pull
git tag 1.3.1
git push origin 1.3.1

IMPORTANT: Most of the time, the develop branch will be in a state that is ready for release. In that case, merging to main amounts to needing rubber-stamp approvals. However, should a reviewer request changes before the release branch is merged to main, then take the following into consideration:

  • Should the release be postponed?
  • If so, then delete the release branch. Next, apply the requested changes in a new PR that will merge to develop as normal. Finally, repeat the steps above to finalize the package release.
  • If the release should not (or cannot) be postponed, then it will be necessary to merge main back to develop after finalizing the package release. More information on merging main into develop can be found in the section below that covers creating a hot-fix release.

Making a Hot-Fix Release

There are times when we need to create a hot-fix release for a package separately from what is on develop. For the purposes of the example below, assume that main has been tagged most recently as version 1.3.1, and we need to make a 1.3.2 release without incorporating anything from the develop branch.

NOTE: As we use Swift Package Manager today, our internal packages are set up so that the Banno Mobile app will automatically get new package versions up to the next major version number. Hence, a package-level hot-fix release can go into app builds without necessarily having to make a new release of the app. We may still make a new version of the app depending on the circumstance, but it may very well be a version-only release. The updates to the package will be included in subsequent app builds without further app-level changes.

The high level process for creating a hot-fix release goes like this:

  1. Create a hotfix/1.3.2 branch relative to the current state of main. (In other words, the HEAD of main should show a commit that is tagged as 1.3.1.)
  2. Apply the necessary fixes. Depending on the circumstances, these may go into a branch set up to merge back to hotfix/1.3.2, or they may go straight to the hotfix/1.3.2 branch. Either way, review is still required at some point before going to the next step.
  3. Open a PR that will merge hotfix/1.3.2 to main.
  4. Tag the 1.3.2 release.
  5. Merge main to develop.

After the 1.3.2 tag is in place, then a PR must be opened to get the hot-fix changes from main into develop. Remember, the work for the hot-fix release was done relative to main, and the develop branch does not have the changes that went into 1.3.2. This can be achieved in multiple ways, and the commands below are just one example:

git switch develop
git switch -c merge_main_1.3.2
git merge main
git push --set-upstream origin HEAD

If there are merge conflicts resulting from the merge command, then those have to be fixed first, of course. Once the branch merge_main_1.3.1 is pushed to GitHub successfully, then the PR can be opened to apply that branch to develop.

Publishing the Release on GitHub

TIP: It is possible to use the publication of a release on GitHub as an alternative to tagging main directly. GitHub will end up creating the tag for you. The end result is the same.

Publishing a release on GitHub is how we record information about a given package version. GitHub provides a helpful interface for automatically populating the release notes with the list of pull requests that went into a release, including identifying authors. For the purposes of this example, we will continue to refer to package version 1.3.1.

  1. Load the GitHub page for the package repository and click the tags link located to the right of the branch selection pull-down menu.
  2. Click the 1.3.1 tag that was pushed earlier.
  3. Click the Create release from tag button.
  4. Populate the release title field with “1.3.1”. Some packages may have a convention of using “Release 1.3.1” as the title rather than the tag name alone. It is best to follow the existing convention for the package in question. (Having the tag name match the release name exactly was needed for Carthage to be able to retrieve pre-compiled XCFramework archives back when we used Carthage.)
  5. Add information about what changed in the release notes text area. Typically, this will include links to the merged pull requests and a high level description of the release. If there are breaking interface changes, it is a very good idea to identify those out in the release notes. The release notes can be pre-populated by clicking the Generate release notes button above the upper right corner of the text area.
  6. Click Publish release.