# 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