Whoops Hoops

Internal engineering documentation lives under docs/ and in co-located src/**/__docs__/ folders. Run the Docusaurus site locally to browse it all with sidebars and cross-links — see docs-site/README.md.

For data sources, bundled assets, and the project's trademark / attribution posture, see docs/legal/data-attribution.md.

Development

Firebase Analytics

Debug mode

To see events in real-time in Firebase DebugView, launch the app with the debug flag:

xcrun simctl launch booted com.lc575757.WhoopsHoops -FIRAnalyticsDebugEnabled

If the app is already running, terminate it first:

xcrun simctl terminate booted com.lc575757.WhoopsHoops
xcrun simctl launch booted com.lc575757.WhoopsHoops -FIRAnalyticsDebugEnabled

To disable debug mode, launch without the flag or pass -FIRAnalyticsDebugDisabled:

xcrun simctl launch booted com.lc575757.WhoopsHoops -FIRAnalyticsDebugDisabled

Custom events

Event	Trigger	Parameters
guess_submitted	Player guessed	guess_count, is_correct
game_won	Correct guess	guess_count, current_streak
hints_opened	Hints panel opened	—
hint_advanced	Next hint tapped	hint_stage
play_again_pressed	Play again after win	—
share_pressed	Share after win	—
history_opened	History modal opened (header or streak pill)	current_streak
history_cleared	User confirmed Clear history	previous_streak, previous_record_count
settings_opened	Settings modal opened (gear icon)	—
reminder_toggle_changed	Master daily-reminders toggle flipped	enabled
reminder_slot_toggled	Preset reminder slot tapped	slot, selected
notification_permission_result	iOS prompt resolved on first launch	status

Full history-event catalog (including the Firebase Console dashboard setup): src/client/lib/history/__docs__/analytics-events.md.

On-device history

Game history persists to AsyncStorage per install. Docs:

• persistence-model-for-storing-game-data-single-user.md — how the event → reducer → blob write path works.
• streak-and-rollover.md — how streak is counted and how rollover reconciliation fires on launch.
• dispatch-flow.svg — end-to-end dispatch diagram.

Contributing

Conventional Commits

Use Conventional Commits for all new commits that are meant to land on main.

Examples:

• feat: add semantic release workflow
• fix: correct commit hook bypass handling
• docs: document ci override procedures
• refactor: split release config helpers

Release automation only bumps versions for:

• feat: -> minor
• fix: -> patch
• ! suffix or BREAKING CHANGE: -> major

Maintenance-only types such as docs:, chore:, and refactor: do not trigger a release.

Release Flow

GitHub Actions runs the test suite for pushes and pull requests. On pushes to main, CI runs semantic-release to:

• update CHANGELOG.md
• update version metadata in package.json and package-lock.json
• create a Git tag

GitHub Releases, Expo EAS builds, and TestFlight publishing are manual steps documented in RELEASE_PROCESS.md.

Emergency Overrides

If an urgent fix needs to bypass local commit validation, use the documented override flow in docs/release/cicd-overrides.md.