Migrating an Astro Project to Swift 3
Table of contents
- Who is this guide for?
- Highlight of changes in Astro to align with Swift 3
- Typical upgrade process
- Known migration issues
Who is this guide for? #
This guide is for Astro developers looking to upgrade a project to the latest version of Swift. It highlights the changes in Swift 3, the changes that have been made to Astro to align with Swift 3, and what the typical upgrade process is.
There is a small list of pre-requisites to update a project to Swift 3:
- You must be running at least Xcode 8.0.
- The first version of Astro to support Swift 3 is Astro version 0.18.
- Make sure your project builds and all tests pass. The swift migrator uses a build action to decide on the changes it suggests, so a project that doesn't build cannot be automatically upgraded.
Highlight of changes in Astro to align with Swift 3 #
Swift 3 brings a large set of changes. It's a good idea to review the changes introduced by Swift 3 before migrating a codebase.
Astro has made a set of changes to ensure the Astro API closely conforms to Swift's recommended API guidelines. Among these changes are:
- Tighter access control: we have adapted the access modifiers for all the Astro classes to take advantage of the new access modifiers provided by Swift 3.
- Changes to naming to conform to the Swift 3 API design guidelines
Typical upgrade process #
If this is the first time you open your project in Xcode 8, you will be prompted to upgrade your project to the latest version of Swift. If you are not prompted, or this is not the first time you open your project in Xcode 8, you can invoke the migration assistant by going to Edit -> Convert -> To Current Swift Syntax...
The migration assistant lets you choose from two different kinds of migration; Swift 2.3 and Swift 3. Choose Swift 3.
Once you have chosen the version of Swift you want to migrate to you will be presented with a list of targets to migrate. Select all applicable targets. The migration assistant will present a preview of the changes for review. Once you've reviewed them, click Save.
It's a good idea to go through all the changes made by the migrator to make sure they are sane. The migrator isn't perfect and even though the code may compile, there will likely be places where the code generated is not ideal.
Tips and tricks
- Resist doing any other refactoring during the migration. Migrate, make a pull request, merge it, then make Swifty API changes in a follow-up pull request to bring your code up-to-date with the latest API guidelines.
- When in doubt about how to properly migrate a piece of code, consult the new swift-evolution proposal status page to find the corresponding proposal. In the "Evolution proposals included in Swift 3.0" section, you’ll find all of the proposals that have been implemented for Swift 3.
After the migration #
After the migration has ended, run your tests to ensure all the functionality you expect still works.
Rejoice in the fact that from now on you will spend time writing Swift 3 code -- not migrating it -- and that's awesome.
Known migration issues #
If you are having issues migrating your project to Swift 3, please check the Known Migration Issues for Swift 3. If the issue appears to be related to Astro and not Swift, please contact Customer Support