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.

Prerequisites

• Know the desired product name. Ask a member of the Product team to confirm the desired name. If the name is something that we have conjured up internally, it is usually wise to check for trademark infringement. Having the desired product name early on will help ensure that all downstream generated credentials match and help to eliminate confusion.

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

• The Bundle Identifier should be a reverse DNS name, like com.[client name].[project name]. Make sure the client actually owns [client name].com to prevent name collisions.
• Remember to set the Organization to Vokal. Unless otherwise agreed with the client, Vokal maintains the copyright on code that we write, and setting the organization here will ensure the generated comments in code files are correct.
• If you did not use the Vokal project template, be sure to follow the setup instructions for Objective-Clean or SwiftLint.
• Adjust the Minimum Passing Line Percent Coverage option in the project settings for the repo on CVR. If the repo is not listed there yet, click the Sync Repos button. The section on testing in the main README notes that we do not have a department-wide minimum for test coverage, so the actual number used will vary from project to 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 git@github.com:yourusername/[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 git@github.com: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.

• Negotiate the API with the systems engineer(s). Make sure that you agree on how data should be represented and formatted, what endpoints are needed, and how the server will behave. Thinking this through early will save a lot of time later on, when you might need to refactor on both the client and server sides, or worse, workaround limitations or assumptions that were made during API development. Ideally, the systems engineer will then produce a proposed API documentation from this conversation, but if not, make sure the decisions are written down for reference.
• Decide what Apple account will be used. For client apps, the app should be setup under their company account. Ideally, we should have admin-level rights in both the developer portal and iTunes Connect, so that we can create provisioning profiles, upload builds, etc. If the client doesn't want to grant us access, make sure the Product Owner and client both understand that extra time will be needed to coordinate efforts to manage the app.
• Make a list of every error message in the app. When preparing to localize an app or get approved copy from the client, we often collect the text strings from the designs. These don't always include every error state, so make sure that all errors are represented in that list. Login and registration alone account for a lot of errors that clients often don't consider: password isn't long enough, email address isn't valid, confirmed password doesn't match, credentials aren't valid, email address is already in use, etc. As such, we should provide a list of these possible errors to the PO so that they (or the client) can supply appropriate error messages to display to the user.