Merge branch 'master' into android-safe-area-insets

.cursor/rules/development/time_examples.mdc

@@ -0,0 +1,243 @@
+# Time Examples — Practical Patterns
+
+> **Agent role**: Reference this file for practical examples and
+  patterns when working with time handling in development.
+
+## Examples
+
+### Good
+
+- "Feature flag rollout started on `2025-08-01` and will be reviewed on
+
+  `2025-08-21`."
+
+- "Migration applied on `2025-07-15T14:00Z`."
+
+- "Issue reproduced on `2025-08-17T09:00-05:00 (local)` /
+
+  `2025-08-17T14:00Z (UTC)`."
+
+### Bad
+
+- "Feature flag rolled out last week."
+
+- "Migration applied recently."
+
+- "Now is August, so we assume this was last month."
+
+### More Examples
+
+#### Issue Reports
+
+- ✅ **Good**: "User reported login failure at `2025-08-17T14:30:00Z`. Issue
+
+  persisted until `2025-08-17T15:45:00Z`."
+
+- ❌ **Bad**: "User reported login failure earlier today. Issue lasted for a
+
+  while."
+
+#### Release Planning
+
+- ✅ **Good**: "Feature X scheduled for release on `2025-08-25`. Testing
+
+  window: `2025-08-20` to `2025-08-24`."
+
+- ❌ **Bad**: "Feature X will be released next week after testing."
+
+#### Performance Monitoring
+
+- ✅ **Good**: "Baseline performance measured on `2025-08-10T09:00:00Z`.
+
+  Regression detected on `2025-08-15T14:00:00Z`."
+
+- ❌ **Bad**: "Performance was good last week but got worse this week."
+
+## Technical Implementation Examples
+
+### Database Storage
+
+```sql
+
+-- ✅ Good: Store in UTC
+created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+
+-- ❌ Bad: Store in local time
+created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+
+```
+
+### API Responses
+
+```json
+
+// ✅ Good: Include both UTC and local time
+{
+  "eventTime": "2025-08-17T14:00:00Z",
+  "localTime": "2025-08-17T10:00:00-04:00",
+  "timezone": "America/New_York"
+}
+
+// ❌ Bad: Only local time
+{
+  "eventTime": "2025-08-17T10:00:00-04:00"
+}
+
+```
+
+### Logging
+
+```python
+
+# ✅ Good: Log in UTC with timezone info
+
+logger.info(f"User action at {datetime.utcnow().isoformat()}Z (UTC)")
+
+# ❌ Bad: Log in local time
+
+logger.info(f"User action at {datetime.now()}")
+
+```
+
+## Timezone Handling Examples
+
+### Good Timezone Usage
+
+```typescript
+
+// ✅ Good: Store UTC, convert for display
+const eventTime = new Date().toISOString(); // Store in UTC
+const localTime = new Date().toLocaleString('en-US', {
+  timeZone: 'America/New_York'
+}); // Convert for display
+
+// ✅ Good: Include timezone context
+const timestamp = {
+  utc: "2025-08-17T14:00:00Z",
+  local: "2025-08-17T10:00:00-04:00",
+  timezone: "America/New_York"
+};
+
+```
+
+### Bad Timezone Usage
+
+```typescript
+
+// ❌ Bad: Assume timezone
+const now = new Date(); // Assumes system timezone
+
+// ❌ Bad: Mix formats
+const timestamp = "2025-08-17 10:00 AM"; // Ambiguous format
+
+```
+
+## Common Patterns
+
+### Date Range References
+
+```typescript
+
+// ✅ Good: Explicit date ranges
+const dateRange = {
+  start: "2025-08-01T00:00:00Z",
+  end: "2025-08-31T23:59:59Z"
+};
+
+// ❌ Bad: Relative ranges
+const dateRange = {
+  start: "beginning of month",
+  end: "end of month"
+};
+
+```
+
+### Duration References
+
+```typescript
+
+// ✅ Good: Specific durations
+const duration = {
+  value: 30,
+  unit: "days",
+  startDate: "2025-08-01T00:00:00Z"
+};
+
+// ❌ Bad: Vague durations
+const duration = "about a month";
+
+```
+
+### Version References
+
+```typescript
+
+// ✅ Good: Version with date
+const version = {
+  number: "1.2.3",
+  releaseDate: "2025-08-17T10:00:00Z",
+  buildDate: "2025-08-17T09:30:00Z"
+};
+
+// ❌ Bad: Version without context
+const version = "latest";
+
+```
+
+## References
+
+- [ISO 8601 Date and Time Standard](https://en.wikipedia.org/wiki/ISO_8601)
+
+- [IANA Timezone Database](https://www.iana.org/time-zones)
+
+- [ADR Template](./adr_template.md)
+
+- [Research & Diagnostic Workflow](./research_diagnostic.mdc)
+
+---
+
+**Rule of Thumb**: Every time reference in development artifacts should be
+**clear in 6 months without context**, and aligned to the **developer's actual
+current time**.
+
+**Technical Rule of Thumb**: **Store in UTC, display in local time, always
+include timezone context.**
+
+---
+
+**See also**:
+
+- `.cursor/rules/development/time.mdc` for core principles
+
+- `.cursor/rules/development/time_implementation.mdc` for implementation instructions
+
+**Status**: Active examples and patterns
+**Priority**: Medium
+**Estimated Effort**: Ongoing reference
+**Dependencies**: time.mdc, time_implementation.mdc
+**Stakeholders**: Development team, Documentation team
+
+## Model Implementation Checklist
+
+### Before Time Implementation
+
+- [ ] **Time Context**: Understand what time information needs to be implemented
+- [ ] **Format Review**: Review time formatting standards (UTC, ISO 8601)
+- [ ] **Platform Check**: Identify platform-specific time requirements
+- [ ] **User Context**: Consider user's timezone and display preferences
+
+### During Time Implementation
+
+- [ ] **UTC Storage**: Use UTC for all system and log timestamps
+- [ ] **Format Consistency**: Apply consistent time formatting patterns
+- [ ] **Timezone Handling**: Properly handle timezone conversions
+- [ ] **User Display**: Format times appropriately for user display
+
+### After Time Implementation
+
+- [ ] **Format Validation**: Verify time formats are correct and consistent
+- [ ] **Cross-Platform Testing**: Test time handling across different platforms
+- [ ] **Documentation**: Update relevant documentation with time patterns
+- [ ] **User Experience**: Confirm time display is clear and user-friendly