Skip to content

Releases

Jump to bottom
Sam Yanez edited this page Jun 6, 2026 · 2 revisions

Releases

This document describes the release process, versioning strategy, branching model, tagging conventions, and hotfix workflow for this project.

Branch Strategy

Main Branch

main is the primary development branch and always contains the next version under development.

Examples:

Branch Purpose
main Ongoing development
release/1.0 Stabilization and maintenance of the 1.0 release line
release/1.1 Stabilization and maintenance of the 1.1 release line

Versioning

The app follows Semantic Versioning:

MAJOR.MINOR.PATCH

Examples:

1.0.0
1.0.1
1.1.0
2.0.0

App Version

The version shown in Xcode and App Store Connect uses the full semantic version.

Examples:

Release Version
Initial Release 1.0.0
Bug Fix Release 1.0.1
Feature Release 1.1.0
Major Release 2.0.0

Version Number Rules

Change Type Example
New features 1.0.0 → 1.1.0
Bug fixes 1.0.0 → 1.0.1
Breaking changes 1.0.0 → 2.0.0

Build Numbers

Build numbers are managed automatically by Xcode Cloud.

Examples:

Version Build
1.0.0 1024
1.0.0 1025
1.0.0 1026
1.0.1 1030

Requirements:

  • Build numbers must always increase.
  • Multiple builds may exist for the same version.
  • Only one build is ultimately released.

Release Branches

Release branches are created when development for a release is complete and the app enters stabilization.

Format:

release/<major>.<minor>

Examples:

release/1.0
release/1.1
release/2.0

Release branches may contain:

  • Bug fixes
  • App Store review fixes
  • Localization updates
  • Release-specific changes

Release branches should not contain:

  • New features
  • Large refactors
  • Experimental work

Release Process

1. Create Release Branch

Create a release branch from main.

git checkout main
git pull
git checkout -b release/1.0
git push -u origin release/1.0

2. Set Release Version

Update the app version in Xcode.

Example:

1.0.0

Commit the version update.

git add .
git commit -m "Prepare 1.0.0 release"
git push

3. Submit to App Store Connect

Push changes to the release branch.

Xcode Cloud will:

  • Build the app
  • Run tests
  • Upload to TestFlight
  • Prepare App Store submission

Submit the desired build for review.

4. App Review

During review:

  • Fix review issues on the release branch.
  • Create additional builds as needed.
  • Do not merge new features into the release branch.

5. Tag the Approved Commit

After approval (or immediately before release), tag the exact commit that ships.

git checkout release/1.0

git tag v1.0.0

git push origin v1.0.0

Tags represent shipped releases.

Examples:

v1.0.0
v1.0.1
v1.1.0

6. Create GitHub Release

Create a GitHub Release using the newly created tag.

GitHub → Releases → Draft a new release

Use:

Tag: v1.0.0
Title: v1.0.0

Add release notes describing user-facing changes.

## What's Changed

- Added onboarding flow
- Improved performance of photo uploads
- Fixed login issue affecting some users

7. Merge Back to Main

After release:

git checkout main

git merge release/1.0

git push origin main

This ensures any release fixes are preserved.

8. Begin Next Release

Continue development on main.

Example:

Current Release: 1.0.0
Next Development Version: 1.1.0

Hotfix Process

Hotfixes are created when a production issue must be fixed after release.

Current production version:

1.0.0

A critical issue is discovered.

1. Create Fix

git checkout release/1.0

git checkout -b hotfix/1.0.1

Apply the fix.

Update version:

1.0.1

Push and submit for review.

2. Tag Release

After approval:

git tag v1.0.1

git push origin v1.0.1

3. Merge Back

git checkout main

git merge hotfix/1.0.1

git push origin main

Tagging Strategy

Tags identify exactly what was released.

Format:

v<major>.<minor>.<patch>

Examples:

v1.0.0
v1.0.1
v1.1.0
v2.0.0

Rules:

  • Every App Store release gets a tag.
  • Tags are created after approval.
  • Tags point to the exact commit that shipped.

Xcode Cloud

Release workflows should trigger on:

release/*

Examples:

Branch Action
main Development builds
release/* TestFlight / App Store builds

This allows any release branch to automatically generate release candidates.

Example Timeline

Release 1.0

main
 └── release/1.0
       └── v1.0.0

Hotfix

release/1.0
 └── v1.0.1

Next Release

main
 └── release/1.1
       └── v1.1.0

Summary

Item Convention
Development Branch main
Release Branch release/<major>.<minor>
App Version 1.0.0
Build Number Xcode Cloud-generated
Release Tag v1.0.0
Tag Timing After approval
Hotfix Branch hotfix/<version>

Release branches represent a release line, while tags represent the exact versions that ship to customers.

Clone this wiki locally