Versioning iPhone App: Beta & Production Builds

A little bit of Google search yields the following great resources to help get started in the arena of versioning your iOS apps:

• easy-iphone-application-versioning-with-agvtool
• recipe-automatic-version-number-build-number-build-date-handling
• setting-ios-application-build-versions

In this blog entry, I'll:

• attempt to provide the grand total of everything I learned from these articles which are based in XCode3,
• provide instructions on how to do the same in XCode4, and
• explain some of the finer points which weren't clear to me without trial & error.

1. This snapshot shows how to add apple generic versioning to your XCode4 project.

2. Open YOUR_PROJECT in XCode 4 and navigate to YOUR_PROJECT > Targets > YOUR_PROJECT > Summary > iOS Application Target > Version
   
3. Even though it may seem intuitive to think so but this is NOT the version number that the iPhone app users will see.
4. Instead this is an internal build number that you can increment as many times as you like and whenever you deem appropriate. Follow the links at the top to learn more.

5. You can easily comfirm this by attempting to edit this property in YOUR_PROJECT > Target > YOUR_PROJECT > Info (maps to YOUR_PROJECT-Info.plist file) > Custom iOS Target Properties > Bundle Version
   and then confirming that the change took effect again in Summary > iOS Application Target > Version
   

6. If you Ctrl+click and ask it to Show raw keys/values

7. Then you'll notice that this maps to the key: CFBundleVersion
8. If you would eventually like to build your "About" page in the app and format a string that shows up something like version 0.1.0 (build 42), where 42 will correspond to the value of CFBundleVersion, then instead of giving it an initial value like 1.0, I would suggest setting it to 1

9. So now what corresponds to the 0.1.0 part of the version 0.1.0 (build 42) in your about page? Well, the Bundle versions string, short property with the raw key value of CFBundleShortVersionString would make up the 0.1.0 piece of that string.

10. And could this 0.1.0 be the version # that is displayed as your app's version in the App Store? Yes! this is known as the marketing version and it is what shows up to the users of the App Store.
11. What's up with the x.y.z version structure? As one of the links in the beginning explains, X - major revision number, Y - minor revision number, Z - maintenance or patch release. This is a very nice & simple concept to use.
12. Why should the starting of an App's marketing version be from 0.1.0? Because an application would like to enter the App Store as 1.0.0, so you don't want to use 1 as your major (X) version in the very beginning when you are probably in the process of distributing Ad-Hoc builds for alpha/beta testing. 1 as your minor (Y) version makes sense 0.1.0 because your app starts with the smallest set of features and then grows to perhaps 0.2.0, 0.3.0 and so on. Also the 0 as your patch (Z) version makes sense because there is nothing for you to patch at the very start. In conclusion: minor.major.patch is conveniently 0.1.0 for starters.
13. Here's what my email notification message looks like when I use TestFlightApp to publish beta builds to testers: v0.1.0 (4) of ShoppinPal is ready for a TestFlight
14. To check your CFBundleVersion via Terminal, use:

    agvtool what-version

15. All the following commands increment CFBundleVersion by 1 but do nothing to CFBundleShortVersionString:

    agvtool next-version
    agvtool next-version -all
    agvtool bump -all

16. To check your CFBundleShortVersionString via Terminal, use:

    agvtool what-marketing-version

17. To change CFBundleShortVersionString, you will yourself have to understand if the change is major, minor or patch and then use:
    

    agvtool new-marketing-version 0.2.0

18. With XCode4 there really shouldn't be any good reason not to use Git so remember to commit to the repository every time after you change the version. Perhaps even take the time to tag the repo so that you can pull the exact source for debugging if someone ever reports an issue against a specific version/build #