Creating An iOS Project From Scratch

These guidelines for creating a new iOS project will get you up and running with minimal fuss. Follow these instructions in order; lessons have been learned.

1. Create the GitHub repo

  1. Have someone with create permissions on GitHub (a senior engineer or director) create a private Vokal repo. The repo should be created with a README, but do not include a .gitignore.
  2. Fork that repo to your GitHub account.
  3. On your fork, use the GitHub UI to delete the README and commit that change to master.
    • Yes, this is a bit convoluted. The project template provides a starter README and .gitignore for the project, which will conflict with the ones that GitHub can add when the repo is created. But, you can't just create an empty repo, because then GitHub won't let you fork it to your account. As such, we recommend that you just add the GitHub-supplied README when the repo is created, then delete it right after forking. This will make life easier later.
  4. Do not clone the repo. You'll handle the repo setup a bit later, after creating the Xcode project, as explained in the next section.

Note that if you clone the repo, and then create the project in that directory, Xcode will put all the project files inside another subdirectory in the cloned repo directory. This isn't the end of the world, because you can just move all the files back up a level; creating the project first, before cloning, just helps to ensure that hidden files don't get lost in that shuffle.

2. Create the Xcode project

The Vokal Xcode project template contains a lot of helpful scripts and configuration, and should be used whenever possible. Unless you have a really, really good reason not to, the Vokal project template should be used for all new iOS projects.

  1. Download and install our Xcode project template. If you have previously done this, make sure you update it to the latest version.
  2. Determine if you want to use Swift, Objective-C, or some combination of the two.
  3. Launch Xcode, create a new project, and select the appropriate Vokal template (either Swift or Objective-C).
  4. Make selections from the available options based on what libraries and CocoaPods you expect to need.
    • When using Objective-C, the Class Prefix should be a unique and easily recognizable three letter string (ABR for AisleBuyer, THR for Threadless, etc.). For pure Swift projects, prefixes are not necessary.
    • If you plan to use both Swift and Objective-C in a single project, please make sure you read Apple's interoperability documentation and understand the potential problems with doing so before you add whichever language you didn't start with.
  5. Be sure to follow the After creating a project instructions in the project template instructions to finish project setup, before continuing with section 3 below.

3. Configure the project

4. Setup git remotes

  1. Go into the new project directory and initialize a git repo: git init
  2. Add your fork as a tracked repo (replace the project URL):

    git remote add origin[ProjectName-iOS].git
  3. Add the original Vokal repo as a tracked repo, so you can pull upstream changes (again, replace the project URL):

    git remote add vokal[ProjectName-iOS].git
  4. Pull from your fork to fetch the initial commit, and the commit in which you removed the GitHub-provided README, by executing git pull -t origin master

5. Open a Pull Request

If you're using CocoaPods and haven't done so already, run bundle exec pod install in your project, then commit all of the starting code that has been created from the template and for the CocoaPods.

Then, open your first pull request for the project. That way, the person who reviews your code can just give the whole thing a once-over and confirm it's all boilerplate code. If you wait and open your first pull request after writing code, they'll have to dig through all of that boilerplate to find and review your work, which is a real pain.

You should open a pull request after completing a major feature, or some portion of one, or fixing a group of bugs. Basically, you want to make it convenient for other people to review your code: you shouldn't include too much into one pull request (more than a few hundred lines of changes), nor should you spam everyone by opening a whole bunch of small ones. In general, though, err on the side of smaller pull requests, since more email is usually preferable to reviewing giant code diffs. Don't worry, you'll get a feel for the right size.

6. Configure Travis

More details can be found in the Travis document. Do as much of the Travis config as you can at this point. You'll probably need to come fill in some gaps later on.

Other things to do soon

These tasks aren't related to setting up the code base and build toolchain, but need to be done early in development on client projects. Make sure you don't forget about them.