Documentation/Jutsu/Cocoapods/ skills /cocoapods-publishing-workflow

📖 cocoapods-publishing-workflow

Use when publishing CocoaPods libraries to CocoaPods Trunk. Covers pod trunk registration, podspec validation, version management, and publishing best practices for successful library distribution.


Overview

Complete guide to publishing your CocoaPods library to the official CocoaPods Trunk.

Publishing Overview

Process Steps

  1. Register with CocoaPods Trunk (one-time)
  2. Prepare your podspec
  3. Validate locally (pod lib lint)
  4. Validate for publishing (pod spec lint)
  5. Tag version in git
  6. Push to Trunk (pod trunk push)

Trunk Registration

Register Email (One-Time)

# Register your email
pod trunk register email@example.com 'Your Name'

# Verify email (check inbox for verification link)
# Click link in email to activate account

Check Registration

# Verify registration
pod trunk me

# Sample output:
# - Name:     Your Name
# - Email:    email@example.com
# - Since:    January 1st, 2024
# - Pods:     None

Podspec Preparation

Version Management

Pod::Spec.new do |spec|
  # Semantic versioning: MAJOR.MINOR.PATCH
  spec.version = '1.0.0'

  # Must match git tag
  spec.source = {
    :git => 'https://github.com/username/MyLibrary.git',
    :tag => spec.version.to_s
  }
end

Required Metadata

Pod::Spec.new do |spec|
  # Identity (required)
  spec.name         = 'MyLibrary'
  spec.version      = '1.0.0'

  # Description (required)
  spec.summary      = 'Brief one-line description'
  spec.description  = 'Longer description with more details about what the library does'

  # Links (required)
  spec.homepage     = 'https://github.com/username/MyLibrary'
  spec.source       = { :git => 'https://github.com/username/MyLibrary.git', :tag => spec.version.to_s }

  # License (required)
  spec.license      = { :type => 'MIT', :file => 'LICENSE' }

  # Authors (required)
  spec.authors      = { 'Your Name' => 'email@example.com' }

  # Platform (required)
  spec.ios.deployment_target = '13.0'
end

Local Validation

Quick Validation

# Fast validation (skips build)
pod lib lint --quick

# Check for common issues without full build

Full Validation

# Complete validation with build
pod lib lint

# With Swift version
pod lib lint --swift-version=5.9

# Verbose output
pod lib lint --verbose

Handle Warnings

# Allow warnings (not recommended for new pods)
pod lib lint --allow-warnings

# Better: Fix warnings
pod lib lint
# Address each warning individually

Publishing Validation

Spec Lint

# Validate podspec for publishing
pod spec lint

# Validates against remote repository
# Simulates real-world installation

Pre-Publishing Checklist

  • All tests pass
  • No lint warnings
  • Privacy manifest included (iOS 17+)
  • README is complete
  • LICENSE file exists
  • CHANGELOG updated
  • Version number is correct
  • Git repository is clean

Git Tagging

Create Tag

# Stage all changes
git add .

# Commit changes
git commit -m "Release version 1.0.0"

# Create tag matching podspec version
git tag 1.0.0

# Push to remote with tags
git push origin main --tags

Tag Format

# Semantic versioning
git tag 1.0.0      # MAJOR.MINOR.PATCH
git tag 1.0.0-beta.1  # Pre-release
git tag 1.0.0-rc.1    # Release candidate

# Must match spec.version in podspec

Publishing to Trunk

Push Pod

# Push to CocoaPods Trunk
pod trunk push MyLibrary.podspec

# With specific Swift version
pod trunk push MyLibrary.podspec --swift-version=5.9

# Allow warnings (not recommended)
pod trunk push MyLibrary.podspec --allow-warnings

Successful Publish Output

Validating podspec
 -> MyLibrary (1.0.0)

Updating spec repo `trunk`
 -> MyLibrary (1.0.0)

--------------------------------------------------------------------------------
 🎉  Congrats

 🚀  MyLibrary (1.0.0) successfully published
 📅  January 1st, 2024
 🌎  https://cocoapods.org/pods/MyLibrary
 👍  Tell your friends!
--------------------------------------------------------------------------------

Version Updates

Patch Release (Bug Fixes)

# In podspec
spec.version = '1.0.1'  # Was 1.0.0

# Git workflow
git add .
git commit -m "Fix: Resolve crash in background mode"
git tag 1.0.1
git push origin main --tags
pod trunk push MyLibrary.podspec

Minor Release (New Features)

# In podspec
spec.version = '1.1.0'  # Was 1.0.1

# Git workflow
git add .
git commit -m "Add: Support for custom themes"
git tag 1.1.0
git push origin main --tags
pod trunk push MyLibrary.podspec

Major Release (Breaking Changes)

# In podspec
spec.version = '2.0.0'  # Was 1.1.0

# Git workflow
git add .
git commit -m "BREAKING: Refactor API for modern Swift"
git tag 2.0.0
git push origin main --tags
pod trunk push MyLibrary.podspec

Managing Multiple Pods

List Your Pods

# View all your published pods
pod trunk me

# Shows:
# - Pods:
#   - MyLibrary
#   - MyOtherLibrary

Add Contributors

# Add team member to pod
pod trunk add-owner MyLibrary email@example.com

# Remove contributor
pod trunk remove-owner MyLibrary email@example.com

Deprecation

Deprecate Old Version

# Deprecate specific version
pod trunk deprecate MyLibrary --version=1.0.0

# Deprecate entire pod
pod trunk deprecate MyLibrary

Deprecation with Replacement

# In podspec
spec.deprecated = true
spec.deprecated_in_favor_of = 'NewAwesomeLibrary'

Common Issues

Issue: Tag Doesn't Match

ERROR | [MyLibrary] The repo has no tag for version 1.0.0

Solution:

# Create and push tag
git tag 1.0.0
git push origin --tags

Issue: Validation Fails

ERROR | [MyLibrary] xcodebuild: Returned an unsuccessful exit code

Solution:

# Run detailed validation
pod lib lint --verbose

# Fix errors shown in output
# Re-validate until clean

Issue: Missing License

ERROR | [MyLibrary] Missing required attribute `license`

Solution:

# Add to podspec
spec.license = { :type => 'MIT', :file => 'LICENSE' }

# Create LICENSE file in repo root

Best Practices

Pre-Publish Testing

# 1. Test in example app
cd Example
pod install
# Run app, verify functionality

# 2. Test in real project
# Create test project, add pod from local path
pod 'MyLibrary', :path => '../MyLibrary'

# 3. Validate
pod lib lint
pod spec lint

Version Numbering

# Follow semantic versioning strictly
spec.version = '1.0.0'  # Initial release
spec.version = '1.0.1'  # Bug fix
spec.version = '1.1.0'  # New feature
spec.version = '2.0.0'  # Breaking change

CHANGELOG

# Changelog

## [1.1.0] - 2024-01-15
### Added
- Custom theme support
- Dark mode compatibility

### Fixed
- Memory leak in background processing

## [1.0.0] - 2024-01-01
- Initial release

README

# MyLibrary

Brief description of library.

## Installation

\`\`\`ruby
pod 'MyLibrary', '~> 1.0'
\`\`\`

## Usage

\`\`\`swift
import MyLibrary

let library = MyLibrary()
library.doSomething()
\`\`\`

## Requirements

- iOS 13.0+
- Swift 5.7+

## License

MyLibrary is available under the MIT license.

Anti-Patterns

Don't

❌ Publish without testing

pod trunk push --skip-tests  # Risky

❌ Use --allow-warnings for initial release

pod trunk push --allow-warnings  # Fix warnings instead

❌ Forget to tag git

# Missing git tag - publish will fail
pod trunk push

❌ Skip version bump

# Still version 1.0.0 after changes - confusing
spec.version = '1.0.0'

Do

✅ Test thoroughly before publishing

pod lib lint
pod spec lint
# Test in real project

✅ Fix all warnings

pod lib lint
# Address warnings

✅ Always tag git

git tag 1.0.0
git push --tags

✅ Bump version for every release

spec.version = '1.0.1'  # Incremented

Complete Publishing Example

# 1. Prepare podspec
vim MyLibrary.podspec
# Update version to 1.0.0

# 2. Update CHANGELOG
vim CHANGELOG.md
# Document changes

# 3. Commit and tag
git add .
git commit -m "Release 1.0.0: Initial public release"
git tag 1.0.0
git push origin main --tags

# 4. Validate locally
pod lib lint

# 5. Validate for publishing
pod spec lint

# 6. Publish
pod trunk push MyLibrary.podspec

# 7. Verify
pod search MyLibrary
# Should show your new pod

Related Skills

  • cocoapods-podspec-fundamentals
  • cocoapods-subspecs-organization
  • cocoapods-test-specs
  • cocoapods-privacy-manifests