Kingfisher/docs/deployment.md

Deployment Guide

This document provides comprehensive guidance for deploying Kingfisher across different platforms and distribution channels.

Overview

Kingfisher supports multiple deployment strategies:

• CocoaPods: Traditional CocoaPods spec deployment
• Swift Package Manager: Native Swift package distribution
• XCFramework: Pre-built universal frameworks
• GitHub Releases: Automated release management

The deployment process is fully automated using Fastlane with comprehensive platform coverage across iOS, macOS, tvOS, watchOS, and visionOS.

Package Types

CocoaPods Distribution

Configuration File: /Users/onevcat/Sync/github/Kingfisher/Kingfisher.podspec

Build Targets:

• iOS 13.0+
• macOS 10.15+
• tvOS 13.0+
• watchOS 6.0+
• visionOS 1.0+

Key Features:

• Module stability enabled (BUILD_LIBRARY_FOR_DISTRIBUTION)
• Privacy manifest included (PrivacyInfo.xcprivacy)
• Weak framework dependencies (SwiftUI, Combine)
• Required frameworks (CFNetwork, Accelerate)

Swift Package Manager

Configuration File: /Users/onevcat/Sync/github/Kingfisher/Package.swift

Build Targets:

• Single library target: Kingfisher
• Source path: Sources/
• Minimum Swift tools version: 5.1

Platform Support:

• iOS 13.0+
• macOS 10.15+
• tvOS 13.0+
• watchOS 6.0+

XCFramework Distribution

Output Locations:

build/
├── Kingfisher-{version}.xcframework.zip          # All platforms
├── Kingfisher-iOS-{version}.xcframework.zip      # iOS only
├── Kingfisher-{version}/
│   └── Kingfisher.xcframework/
│       ├── ios-arm64/
│       ├── ios-arm64_x86_64-simulator/
│       ├── macos-arm64_x86_64/
│       ├── tvos-arm64/
│       ├── tvos-arm64_x86_64-simulator/
│       ├── watchos-arm64_arm64_32_armv7k/
│       ├── watchos-arm64_i386_x86_64-simulator/
│       ├── xros-arm64/
│       └── xros-arm64_x86_64-simulator/

Platform-Specific Archives:

build/
├── Kingfisher-iphoneos.xcarchive/
├── Kingfisher-iphonesimulator.xcarchive/
├── Kingfisher-macosx.xcarchive/
├── Kingfisher-appletvos.xcarchive/
├── Kingfisher-appletvsimulator.xcarchive/
├── Kingfisher-watchos.xcarchive/
├── Kingfisher-watchsimulator.xcarchive/
├── Kingfisher-xros.xcarchive/
└── Kingfisher-xrsimulator.xcarchive/

Platform-Specific Deployment

iOS Deployment

• Device: iphoneos SDK
• Simulator: iphonesimulator SDK
• Architectures: arm64, x86_64 (simulator)
• Framework Path: build/Kingfisher-iOS-{version}.xcframework.zip

macOS Deployment

• SDK: macosx
• Architectures: arm64, x86_64 (universal)
• Framework Structure: Traditional bundle format with versioning

tvOS Deployment

• Device: appletvos SDK
• Simulator: appletvsimulator SDK
• Architectures: arm64, x86_64 (simulator)

watchOS Deployment

• Device: watchos SDK
• Simulator: watchsimulator SDK
• Architectures: arm64, arm64_32, armv7k (device), i386, x86_64, arm64 (simulator)

visionOS Deployment

• Device: xros SDK
• Simulator: xrsimulator SDK
• Architectures: arm64, x86_64 (simulator)

Deployment Commands

Complete Release Process

# Full release workflow
bundle exec fastlane release version:X.X.X

# Skip tests during release (not recommended)
bundle exec fastlane release version:X.X.X skip_tests:true

Individual Components

# Create XCFramework only
bundle exec fastlane xcframework version:X.X.X

# Run linting
bundle exec fastlane lint

# Build for specific platform
bundle exec fastlane build_ci

CocoaPods Deployment

# Lint podspec
pod lib lint Kingfisher.podspec

# Push to CocoaPods trunk (automated in release)
pod trunk push Kingfisher.podspec

Swift Package Manager

# Build with SPM
swift build

# Test with SPM
swift test

# Validate package
swift package resolve

Continuous Integration

GitHub Actions Workflows

Build Workflow: .github/workflows/build.yaml

• Builds across multiple Xcode versions (15.2, 15.3, 16.0, 16.1)
• Tests all platforms in matrix configuration
• Uses self-hosted runners

Test Workflow: .github/workflows/test.yaml

• Runs tests on Xcode 15.4 and 16.2
• Covers all platform destinations
• Concurrent execution with cancellation

Matrix Configuration:

destination: [
  'macOS',
  'iOS Simulator,name=iPhone 15,OS=17.5',
  'tvOS Simulator,name=Apple TV,OS=17.5',
  'watchOS Simulator,name=Apple Watch Series 9 (41mm),OS=10.5'
]

Release Management

Automated Release Process

The release process handles:

1. Pre-release Validation:

   • Git branch verification
   • Clean git status check
   • Comprehensive testing across platforms
   • Podspec and SPM linting

2. Version Management:

   • Build number synchronization
   • Version number increment
   • Podspec version update
   • Changelog extraction

3. Build Artifacts:

   • XCFramework creation for all platforms
   • Code signing with Apple Distribution certificate
   • ZIP archive creation

4. Distribution:

   • Git tag creation with signing
   • GitHub release creation
   • Asset upload (both full and iOS-only XCFrameworks)
   • CocoaPods trunk push

Changelog Management

Configuration: /Users/onevcat/Sync/github/Kingfisher/pre-change.yml

Structure:

version: X.X.X
name: Release Name
fix:
  - Bug fix descriptions with issue links
add:
  - New feature descriptions

Version Tagging

• Format: Semantic versioning (X.X.X)
• Signing: GPG signed tags
• Automation: Integrated with release workflow

Reference

Deployment Scripts

Script Location	Purpose
fastlane/Fastfile	Main deployment automation
.github/workflows/build.yaml	CI build workflow
.github/workflows/test.yaml	CI test workflow
Gemfile	Ruby dependencies

Build Output Locations

Package Type	Location
CocoaPods	Published to CocoaPods trunk
Swift Package Manager	Git repository tags
XCFramework (All)	build/Kingfisher-{version}.xcframework.zip
XCFramework (iOS)	build/Kingfisher-iOS-{version}.xcframework.zip
GitHub Release Assets	Attached to release tags

Environment Variables

Variable	Purpose	Required
GITHUB_TOKEN	GitHub API authentication	Yes (release)
DESTINATION	CI build destination	Yes (CI)
XCODE_VERSION	Xcode version selection	Yes (CI)

Code Signing

• Certificate: Apple Distribution: Wei Wang (A4YJ9MRZ66)
• Timestamp: Enabled for all XCFramework builds
• Verification: Automated signature verification

Server Configurations

GitHub Actions:

• Runner Type: Self-hosted
• Concurrency: Group-based with cancellation
• Shell: bash -leo pipefail {0}

Ruby Environment:

• Fastlane: Latest version
• CocoaPods: Latest version
  
• xcode-install: For Xcode version management

This deployment system ensures reliable, automated distribution across all supported Apple platforms with comprehensive testing and validation at each step.