crowd-funder-for-time-pwa/.cursor/rules/development/time_examples.mdc

# 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