docs: make Swift repro README beginner-friendly with comprehensive setup guide#43
Merged
docs: make Swift repro README beginner-friendly with comprehensive setup guide#43
Conversation
…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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Rewrites the Swift reproduction example README to be much more accessible to users who may be unfamiliar with terminal commands, Xcode setup, or the Segment SDK. Adds detailed installation instructions, clarifies Amplitude destination setup, includes comprehensive plugin documentation, and adds a powerful
sharecommand for easy reproduction packaging.Changes
Documentation Improvements
New Share Command Feature
devbox run share: One-command solution for packaging reproductionsswift-repro-a1b2c3d-20260422-143052.zip)shared-repros/: All archives saved to gitignored directoryWhy
Documentation rewrite: The original README assumed familiarity with terminal usage and iOS development tooling. This makes it challenging for:
Share command: Previously, sharing reproductions required Git knowledge and manual steps (commit, clean, zip, name properly). The new
sharecommand makes this a single command, enabling non-technical team members to easily package and share reproductions through standard channels (Jira, email, Slack).Testing
🤖 Generated with Claude Code