Skip to content

docs: make Swift repro example beginner-friendly and ready to run#44

Merged
abueide merged 16 commits intomainfrom
docs/beginner-friendly-swift-repro
Apr 22, 2026
Merged

docs: make Swift repro example beginner-friendly and ready to run#44
abueide merged 16 commits intomainfrom
docs/beginner-friendly-swift-repro

Conversation

@abueide
Copy link
Copy Markdown
Contributor

@abueide abueide commented Apr 22, 2026

Summary

Make the Swift reproduction example beginner-friendly and runnable out of the box without requiring users to manually create configuration files or obtain API keys. Event flushing is automatically enabled when a real write key is configured.

Changes

  • Include Config.swift with demo key: Replace Config.example.swift with ios/Config.swift containing a placeholder write key
  • Conditional event flushing: Automatically detect demo vs real write keys and configure accordingly
    • Demo mode: Events queued locally without flushing (flushAt=1000, flushInterval=0)
    • Live mode: Normal event flushing enabled (flushInterval=10)
  • Remove Config.swift from gitignore: Allow Config.swift to be committed with demo configuration
  • Expand Swift README: Add comprehensive setup instructions, troubleshooting, and architecture explanations
  • Simplify examples README: Make documentation role-agnostic and easier to navigate
  • Add share script: Include convenience script for sharing reproduction cases

Why

New users should be able to run the example immediately after cloning without manual configuration steps. The previous workflow required:

  1. Copying Config.example.swift to Config.swift
  2. Obtaining a Segment write key
  3. Manually configuring the file

This creates friction and barriers to entry. The new approach provides a working demo configuration out of the box while still supporting full functionality when users add their own write key.


🤖 Generated with Claude Code

abueide and others added 15 commits April 22, 2026 15:56
…setup

- Add step-by-step installation instructions for Xcode and Devbox
- Include terminal usage guide for users unfamiliar with command line
- Clarify Amplitude destination setup (no API key needed)
- Document toggle limitation (can't remove plugins once added)
- Add comprehensive plugin system documentation
- Include guide for adding custom and official destination plugins
- Expand troubleshooting section with common beginner issues
- Make language more conversational and less assuming

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Add scripts/share.sh to automate reproduction sharing
- Auto-commits changes, creates zip archive with commit hash + timestamp
- Excludes build artifacts and large files (keeps zip small)
- Includes REPRO-INFO.txt with setup instructions
- Includes git patch showing exact changes
- Outputs to shared-repros/ directory (gitignored)
- Comprehensive documentation for uploading to Jira, email, or Slack
- Beginner-friendly instructions for non-Git users

Benefits:
- Support/CS teams can share repros without Git knowledge
- Consistent naming scheme (commit-hash-timestamp)
- Self-contained packages ready to run
- Clipboard integration on macOS for easy file location

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Document share command workflow in general workflow section
- Add dedicated 'Sharing Made Easy' section with comprehensive details
- Include what's in archives, where to share, and recipient instructions
- Update 'What Makes These Examples Special' to mention easy sharing
- Update 'Adding New Examples' to include share command setup

This makes the share feature discoverable for all reproduction examples.
…inline steps

CRITICAL FIXES:
- Made it crystal clear Xcode must be installed separately (NOT via Devbox)
- Added prominent warnings that Xcode is a separate prerequisite
- Rewrote installation as 'Install Now' steps you can follow immediately
- Added inline Terminal opening instructions (not separate section)
- Included timing expectations (15GB, 30-60 min for Xcode)
- Added visual ✅/❌ indicators for successful/failed verification
- Made 'Close and Reopen Terminal' step more prominent (CRITICAL!)
- Simplified download instructions with exact commands to copy/paste
- Rewrote Quick Start to be more immediate and actionable

The previous docs incorrectly gave the impression Xcode was included.
- Added clear statement that Xcode is NOT included with Devbox
- Split prerequisites into two explicit steps (Xcode, then Devbox)
- Added inline Xcode installation instructions
- Emphasized Terminal restart requirement after Devbox install
- Added note that Devbox requires Xcode for iOS examples
REFACTORING:
- Main README: SDK-agnostic, process-oriented (purpose, sharing, workflow)
- Swift README: Swift-specific setup guide (Xcode, Devbox, running app)

Changes to main README (examples/repro/README.md):
- Rewrote to be SDK-agnostic and conceptual
- Expanded Purpose section with clear audience goals
- Made Workflow section conceptual (not specific commands)
- Kept full Sharing section with complete workflow
- Added quick links to Swift README sections (Prerequisites, Quick Start, etc.)

Changes to Swift README (examples/repro/swift/README.md):
- Removed entire 188-line Sharing section (duplicated from main)
- Updated Step 6 to link to main README for sharing instructions
- Kept Swift-specific content (Xcode/Devbox, plugins, troubleshooting)

Result: 188 lines removed, clear separation of concerns
Remove all role-specific language (CSM, customer, support, engineering).
Focus on 'you' and 'your issue' regardless of reader's role.

Changes:
- Purpose section: No more 'For CSMs', 'For Customers', 'For Engineering'
- New focus: Why/when to use reproductions, benefits
- Workflow: 'your issue' instead of 'customer's issue'
- Sharing: 'Issue Tracker' instead of 'Jira', generic language
- Swift README: 'you encounter' vs 'customer reports'
- Swift README: 'your use case' vs 'their use case'

Result: Documentation works for anyone trying to reproduce an issue
(library users, customers reporting bugs, support teams, engineers)
Changes:
- 'customer support, CSMs, and engineers' → 'you'
- 'Demonstrate the issue clearly' → 'Demonstrate issues clearly'

Consistent with Swift README changes to make docs work for anyone.
Replaced role-specific sections with generic purpose and workflow:

REMOVED:
- 'For Customer Support and CSMs' section
- 'For Customers' section
- 'For Engineering' section

REPLACED WITH:
- Clear 'Why use a reproduction example' bullets
- 'When to use these' scenarios
- Generic workflow using 'you' and 'your issue'

UPDATED:
- All references to 'customer' → 'you'
- 'their SDK' → 'your SDK'
- 'customer's issue' → 'your issue'
- 'Jira' → 'Issue Tracker'

Result: Documentation works for anyone (library users, bug reporters,
support teams, engineers) without assuming organizational role.
- Simplify Available Examples section to clean list format
- Add production write key to Config.example.swift for usage tracking
- Update comments to clarify events help improve the project

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Keep write key as placeholder to avoid potential confusion.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Auto-committed by share.sh for reproduction sharing.

Changes include modifications to demonstrate customer issue.

Co-Authored-By: Share Script <noreply@segment.com>
- Remove commit hash from output (already in filename)
- Change "drag and drop" to "attach" for platform neutrality
- Simplify sharing instructions
- Remove redundant information

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Make the swift repro example work out of the box without requiring
users to create Config.swift manually. Events are queued locally
but not sent to Segment (flushAt set to 1000, flushInterval to 0).

Changes:
- Remove Config.swift from gitignore
- Replace Config.example.swift with ios/Config.swift containing demo key
- Disable automatic event flushing in ContentView.swift

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@abueide abueide added the documentation Improvements or additions to documentation label Apr 22, 2026
Make event flushing conditional based on whether a real write key is configured:
- Demo mode: Events queued locally, flushing disabled (flushAt=1000, flushInterval=0)
- Live mode: Normal event flushing enabled (flushInterval=10)

Changes:
- Add Config.isUsingDemoKey property to detect placeholder keys
- Conditionally configure Analytics based on key type
- Add mode indicator to startup logs

This allows the example to work out of the box with demo key while
still supporting real event transmission when users add their own key.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@abueide abueide marked this pull request as ready for review April 22, 2026 22:33
@abueide abueide merged commit a998a36 into main Apr 22, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant