Skip to content

Distribution

Jump to bottom
Rob Lazzurs edited this page Jan 14, 2026 · 1 revision

Distribution Strategy

OnCall Notify uses a dual distribution strategy to reach users through multiple channels.

Two Distribution Channels

1. Direct Distribution (Already Active)

What it is: Signed and notarized DMG/ZIP files distributed via GitHub Releases

Current Status: ✅ Fully Operational

How it works:

  • Automated builds on every merge to main
  • Signed with Developer ID Application certificate
  • Notarized by Apple
  • Published to GitHub Releases
  • Users download directly from GitHub

Workflow: .github/workflows/release-on-merge.yml

Advantages:

  • ✅ Full control over release timing
  • ✅ No review process or delays
  • ✅ No App Store fees or restrictions
  • ✅ Can update anytime
  • ✅ Direct relationship with users
  • ✅ Faster iteration and bug fixes

Disadvantages:

  • ❌ Users must find your GitHub repo
  • ❌ No built-in update mechanism (yet)
  • ❌ Less discoverable than App Store
  • ❌ Manual download and installation

Best for:

  • Power users and developers
  • Early adopters
  • Users who prefer open source downloads
  • Beta testing

2. Mac App Store Distribution (New - In Setup)

What it is: Official distribution through Apple's Mac App Store

Current Status: 🔧 Ready to Configure

How it works:

  • Manual trigger via GitHub Actions workflow
  • Signed with 3rd Party Mac Developer certificates
  • Builds uploaded to App Store Connect
  • Apple reviews before approval
  • Users install via Mac App Store

Workflow: .github/workflows/appstore-release.yml

Advantages:

  • ✅ Maximum discoverability
  • ✅ Built-in auto-updates
  • ✅ User trust (Apple review badge)
  • ✅ Easier installation for non-technical users
  • ✅ One-click updates

Disadvantages:

  • ❌ 1-3 day review process for each update
  • ❌ Must comply with App Store guidelines
  • ❌ Requires App Sandbox (more restrictive)
  • ❌ Less control over release timing
  • ❌ Requires paid Apple Developer membership ($99/year)

Best for:

  • Mainstream users
  • Users who prefer App Store convenience
  • Organizations with App Store policies
  • Maximum reach

Technical Differences

Aspect Direct Distribution Mac App Store
Certificate Developer ID Application 3rd Party Mac Developer Application
Installer Cert N/A (DMG) 3rd Party Mac Developer Installer
Entitlements Hardened Runtime App Sandbox
Notarization Yes (via notarytool) No (App Store review instead)
Provisioning No Yes (required)
Distribution Format DMG, ZIP PKG (via App Store)
Auto-Updates Not yet (planned) Built-in (App Store)

File Structure

OnCallNotify/
├── OnCallNotify.entitlements              # Direct distribution (Hardened Runtime)
└── OnCallNotify.AppStore.entitlements     # App Store (App Sandbox)

Build Scripts

build.sh              # Local development builds
create-dmg.sh         # DMG creation for direct distribution
build-appstore.sh     # App Store archive and package (NEW)

GitHub Workflows

.github/workflows/
├── release-on-merge.yml    # Automatic: DMG releases on merge to main
├── appstore-release.yml    # Manual: App Store builds (NEW)
└── pr-validation.yml       # PR builds and validation

Recommended Strategy

Phase 1: Direct Distribution (Current)

  • ✅ Keep current automated DMG releases
  • ✅ Build user base
  • ✅ Gather feedback
  • ✅ Iterate quickly

Phase 2: App Store Setup (Next)

  • 📋 Complete App Store Connect setup (see APPSTORE_SETUP.md)
  • 📋 Prepare marketing materials
  • 📋 Submit first version for review
  • 📋 Address any review feedback

Phase 3: Dual Distribution (Future)

  • 🔄 Release updates to both channels
  • 🔄 Direct distribution: Fast iteration, beta features
  • 🔄 App Store: Stable releases, broader audience
  • 🔄 Consider 1-2 week offset (test via direct, then App Store)

Version Management

Recommended Approach

  1. Continuous Direct Distribution

    • Every merge to main creates a GitHub Release
    • Uses semantic versioning from conventional commits
    • Example: v0.16.0, v0.17.0, v0.17.1

  2. Periodic App Store Releases

    • Release to App Store every 2-4 weeks or for major features
    • Use same version numbers as GitHub releases
    • Example: Release v0.17.0 to App Store after testing via direct distribution

  3. Beta Testing

    • Use GitHub Releases for beta testing
    • Use TestFlight for App Store beta testing
    • Gather feedback before wide App Store release

User Communication

Website/GitHub README

## Download OnCall Notify

### Mac App Store (Coming Soon)
[Download from Mac App Store](link) - Recommended for most users
- One-click installation
- Automatic updates
- Apple security review

### Direct Download
[Download DMG](link) - For early access and beta features
- Latest features first
- Direct from GitHub
- Manual installation

Release Strategy

For Direct Distribution:

  • Release notes in GitHub Release
  • Changelog from conventional commits
  • Update README with latest version

For App Store:

  • "What's New" in App Store Connect
  • User-friendly description of changes
  • Highlights user-facing features

Security Considerations

Direct Distribution

  • ✅ Developer ID signed
  • ✅ Notarized by Apple
  • ✅ No Gatekeeper warnings
  • ✅ Hardened Runtime enabled
  • ⚠️ Users must allow from "unidentified developer" (rare, if notarization fails)

App Store

  • ✅ App Store reviewed
  • ✅ App Sandbox enforced
  • ✅ No additional security prompts
  • ✅ Automatic security updates via App Store

Cost Analysis

Direct Distribution

  • Cost: Free (GitHub Actions minutes included with public repo)
  • Developer Certificate: $99/year (one-time for all apps)
  • Storage: Free (GitHub Releases)

App Store

  • Cost: Free to distribute (app is free)
  • Developer Membership: $99/year (required, same as above)
  • Commission: 0% (app is free, no IAP)

Total Annual Cost: $99/year (covers both distribution methods)

Next Steps

To Continue with Direct Distribution Only

  1. ✅ Already set up - no action needed
  2. Keep releasing via GitHub
  3. Build user base organically

To Add App Store Distribution

  1. 📋 Follow APPSTORE_SETUP.md guide
  2. 📋 Set up App Store Connect account
  3. 📋 Create certificates and provisioning
  4. 📋 Configure GitHub secrets
  5. 📋 Prepare marketing materials
  6. 📋 Submit first build for review

To Implement Both (Recommended)

  1. ✅ Continue current direct distribution (no changes)
  2. 📋 Follow App Store setup in parallel
  3. 📋 Release to App Store once approved
  4. 🔄 Maintain both channels going forward

Monitoring and Analytics

Direct Distribution

  • GitHub Release download counts
  • GitHub stars and forks
  • Issue tracker feedback
  • Manual user surveys

App Store

  • App Store Connect Analytics dashboard
  • Download and update statistics
  • User reviews and ratings
  • Crash reports

Support Strategy

Direct Distribution

  • GitHub Issues for bug reports
  • GitHub Discussions for questions
  • Direct user engagement

App Store

  • App Store reviews (respond to feedback)
  • Support URL (points to GitHub Issues)
  • App Store Connect review responses

Future Enhancements

Direct Distribution

  • Auto-update mechanism (Sparkle framework)
  • Update notifications
  • Beta channel option

App Store

  • In-app feedback mechanism
  • App Store rating prompts
  • StoreKit integration (if adding paid features)

Quick Reference

Need Use
Quick bug fix Direct distribution (minutes)
New feature testing Direct distribution (immediate)
Maximum reach App Store (1-3 day review)
Beta testing GitHub Releases or TestFlight
Stable release Both channels

Support

Clone this wiki locally