Skip to content

New Project

  1. Create a new GitHub repository

    Steps

    • open iOS project template and click Use this template -> Create a new repository

      Step 1

    • fill new repository info

      Step 2

      1. change owner to futuredapp
      2. preffered repo name is [product-name]-[platform], where [product-name] includes only name of the product, without client name (like Skoda))
      3. change repo visibility to private
      4. click Create repository button

    • you will be redirected to the new repo in couple of seconds

    • in newly created repo:

      Step 3

      1. click Settings button

      2. edit default branch name -> rename it to develop

        Step 4

      3. disable Wikis (we do not use it)

      4. disable Issues (we do not use it)
      5. disable Projects (we do not use it)
      6. enable Allow auto-merge
      7. enable Automatically delete head branches (there is no need to delete branches manually after each PR merge)

      8. select Rules section

        1. select Rulesets subsection
        2. click New ruleset button

        3. click New branch ruleset option from dropdown

          Step 5

      9. set new branch ruleset

        Step 6

        1. fill default branch protection to Ruleset Name

        2. change Enforcement status to Active

          Step 7

        3. click Include default branch to add default branch as target branch

          Step 8a Step 8b

        4. enable Require a pull request before merging

          Step 9

          1. set Required approvals to 1
          2. enable Dismiss stale pull request approvals when new commits are pushed

        5. keep Require status checks to pass unchecked for the moment (we'll set it up later)

          • don't forget to add the test action rule after opening your first PR (actions will appear in the list after their first run)

          Step 10

        6. click Create button, new ruleset appears in the list

          Step 11

  2. Configure Ruby environment and Fastlane

    Steps
    • clone your project's repo

    • create a new branch feature/PROJ-1-Setup-project where everything will be set up in next steps

      • PROJ is your project Jira identificator
      • 1 is Jira task number (if you don't have Jira yet ask your PM)

    • if you haven't setup ruby on your machine yet

      • follow manual steps of this tutorial
      • install bundler from Terminal with gem install bundler

    • in project folder

    • in Terminal

      • switch to repo root folder
      • call bundle install to install gems

  3. Create app in Apple Developer and App Store Connect portals

    Steps

    • create app in Apple Developer and App Store Connect portals

      App Store Connect 2FA

      If you need a 2FA code for ops@futured.app account when running the following Fastlane commands, please contact someone from the iOS team for assistance.

      App released from customer's ASC account

      If you filled customer's environment variables in Fastfile

      • call bundle exec fastlane create_apps

        • if it's the first app for the account append company_name:"My Company Inc" parameter

      • call bundle exec fastlane update_provisioning include_release:true create_branch:true

        • create_branch:true parameter is needed only for the first time to create customer branch in our Apple certificates repo
      App released from Futured's ASC account
      • call bundle exec fastlane create_apps
      • call bundle exec fastlane update_provisioning include_release:true
      The app's release account is currently unknown

      You can setup release account later

      • call bundle exec fastlane create_apps skip_release_app:true
      • call bundle exec fastlane update_provisioning

      Once you're familiar with the release process, rerun the above command (no need to worry about duplication)

  4. Create a new Xcode project

    Steps

    • install FuturedArchitecture project template (if you haven’t done so yet)

      • paste the following script to Terminal and press enter 
        bash << 'EOF'
#!/bin/bash

echo "Cloning repository..."
git clone --depth=1 git@github.com:futuredapp/FuturedKit.git

echo "Running make..."
(cd FuturedKit/Templates && make)

echo "Cleaning up..."
rm -rf FuturedKit

echo "Done!"
EOF

    • open Xcode (or close and open again for refresh templates) and selectFile -> New -> Project

      Step 1

    • select iOS tab and SwiftUI App from FuturedArchitecture and click Next button

      Step 2

    • fill the project info and click Next button

      • write product name in CamelCased style
      • organization identifier is app.futured

      Step 3

    • choose your repo folder and click Create button

      • Xcode project will open
      • close it and check the project's folder
      • move content of {ProjectName} folder to the repo root (you need to rename it first to be able to move the content)
      • delete {ProjectName} folder
      • open Xcode project again

      Step 4

    • in Xcode:

      • change bundle identifier to kebab-cased style app.futured.kebab-case-app-name

        1. select root
        2. select main project target
        3. select Signing & Capabilities tab
        4. change bundle id for all configurations

        Step 5

      • setup Futured's architecture

        • add FuturedKit package dependency - https://github.com/futuredapp/FuturedKit.git

          Step 6

        • add FuturedArchitecture to main project target

        • optionally add FuturedHelpers to main project target if needed - see docs

          Step 7

        • add futured-macros package dependency - https://github.com/futuredapp/futured-macros.git and add FuturedMacros to main project target (the template files use @EnumIdentable and @ProxyMembers)

        • go to the {project_name}App.swift file and remove error at line 10

          #error("Add https://github.com/futuredapp/FuturedKit.git to the project!")

          Step 8

        • select Issue navigator, click the Macro target ... warning and then click Trust & Enable button

          Step 9

      • set up SwiftFormat and SwiftLint

        • if you don't have them installed locally call brew install swiftformat swiftlint from Terminal
        • the project template already contains the .swiftformat and .swiftlint.yml configuration
        • the Xcode template already adds the SwiftFormat and SwiftLint run script phases and disables User Script Sandboxing for the app target, so no script needs to be pasted
        • go to Build Phases tab
        • drag the SwiftFormat phase and then the SwiftLint phase above Compile Sources, in that order (Xcode templates can only append phases, so both are appended after Compile Sources when the project is created; the #warning in {project_name}App.swift reminds you about it and disappears once you remove it)

        • the phases must be ordered SwiftFormat -> SwiftLint -> Compile Sources, so files are formatted first and SwiftLint then reports what remains

        • for reference, these are the scripts the template generates (the same ones used in current iOS projects); both skip Xcode preview builds

        SwiftFormat phase:

        if [[ "${BUILD_DIR}" =~ "Previews" ]]; then
    echo "SwiftFormat not enabled when compiling for previews"
    exit
fi

if test -d "/opt/homebrew/bin/"; then
  PATH="/opt/homebrew/bin/:${PATH}"
fi

export PATH

if which swiftformat >/dev/null; then
    swiftformat "$SRCROOT"
else
    echo "warning: SwiftFormat not installed, run: brew install swiftformat"
fi

        SwiftLint phase:

        if [[ "${BUILD_DIR}" =~ "Previews" ]]; then
    echo "SwiftLint not enabled when compiling for previews"
    exit
fi

if test -d "/opt/homebrew/bin/"; then
  PATH="/opt/homebrew/bin/:${PATH}"
fi

export PATH

if which swiftlint >/dev/null; then
    swiftlint --fix --quiet
    swiftlint
else
    echo "error: SwiftLint not installed, run: brew install swiftlint"
fi

      • configure the project for Continuous Deployment

        • set proper values in Versioning part of Build Settings

          • select all targets and remove Marketing Version value by pressing Delete button on keyboard (Marketing Version text will change from bold to normal)
          • select project and fill 1.0.0 as Marketing Version

          Step 13 Step 14

        • select appropriate provisioning profiles for all configurations in the Target's Signing & Capabilities tab

          Step 15

      • build the project

  5. Open pull request with the project setup

    Steps

    • update .github/CODEOWNERS file

      • change @futuredapp/ios to @{github_username} of teammate/teammates (or person who will perform code reviews)

    • update project README and fill in all the strike-through points

    • commit everything and open PR

    • after CI checks the PR, test check is now available to be added in default branch protection ruleset

      • add test/test check (for GitHub Actions)

      Step 16

  6. Enjoy!

First app run and it is not in fullscreen? 😱

You have to specify the launch screen. Check the documentation. 👀 TLDR: Add UILaunchScreen key into the project manifest file (Info tab in app's target -> Info.plist)

Tip

Check the Accessibility Basics to conform new project to EAA