You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
146 lines
4.0 KiB
146 lines
4.0 KiB
# Time Handling in Development Workflow
|
|
|
|
**Author**: Matthew Raymer
|
|
**Date**: 2025-08-17
|
|
**Status**: 🎯 **ACTIVE** - Production Ready
|
|
|
|
## Overview
|
|
|
|
This guide establishes **how time should be referenced and used** across the
|
|
development workflow. It is not tied to any one project, but applies to **all
|
|
feature development, issue investigations, ADRs, and documentation**.
|
|
|
|
## General Principles
|
|
|
|
- **Explicit over relative**: Always prefer absolute dates (`2025-08-17`) over
|
|
|
|
relative references like "last week."
|
|
|
|
- **ISO 8601 Standard**: Use `YYYY-MM-DD` format for all date references in
|
|
|
|
docs, issues, ADRs, and commits.
|
|
|
|
- **Time zones**: Default to **UTC** unless explicitly tied to user-facing
|
|
|
|
behavior.
|
|
|
|
- **Precision**: Only specify as much precision as needed (date vs. datetime vs.
|
|
|
|
timestamp).
|
|
|
|
- **Consistency**: Align time references across ADRs, commits, and investigation
|
|
|
|
reports.
|
|
|
|
## In Documentation & ADRs
|
|
|
|
- Record decision dates using **absolute ISO dates**.
|
|
|
|
- For ongoing timelines, state start and end explicitly (e.g., `2025-08-01` →
|
|
|
|
`2025-08-17`).
|
|
|
|
- Avoid ambiguous terms like *recently*, *last month*, or *soon*.
|
|
|
|
- For time-based experiments (e.g., A/B tests), always include:
|
|
|
|
- Start date
|
|
|
|
- Expected duration
|
|
|
|
- Review date checkpoint
|
|
|
|
## In Code & Commits
|
|
|
|
- Use **UTC timestamps** in logs, DB migrations, and serialized formats.
|
|
|
|
- In commits, link changes to **date-bound ADRs or investigation docs**.
|
|
|
|
- For migrations, include both **applied date** and **intended version window**.
|
|
|
|
- Use constants for known fixed dates; avoid hardcoding arbitrary strings.
|
|
|
|
## In Investigations & Research
|
|
|
|
- Capture **when** an issue occurred (absolute time or version tag).
|
|
|
|
- When describing failures: note whether they are **time-sensitive** (e.g.,
|
|
|
|
after
|
|
migrations, cache expirations).
|
|
|
|
- Record diagnostic timelines in ISO format (not relative).
|
|
|
|
- For performance regressions, annotate both **baseline timeframe** and
|
|
|
|
**measurement timeframe**.
|
|
|
|
## Collaboration Hooks
|
|
|
|
- During reviews, verify **time references are clear, absolute, and
|
|
|
|
standardized**.
|
|
|
|
- In syncs, reframe relative terms ("this week") into shared absolute
|
|
|
|
references.
|
|
|
|
- Tag ADRs with both **date created** and **review by** checkpoints.
|
|
|
|
## Self-Check Before Submitting
|
|
|
|
- [ ] Did I check the time using the **developer's actual system time and
|
|
|
|
timezone**?
|
|
|
|
- [ ] Am I using absolute ISO dates?
|
|
|
|
- [ ] Is UTC assumed unless specified otherwise?
|
|
|
|
- [ ] Did I avoid ambiguous relative terms?
|
|
|
|
- [ ] If duration matters, did I specify both start and end?
|
|
|
|
- [ ] For future work, did I include a review/revisit date?
|
|
|
|
---
|
|
|
|
**See also**:
|
|
|
|
- `.cursor/rules/development/time_implementation.mdc` for
|
|
|
|
detailed implementation instructions
|
|
|
|
- `.cursor/rules/development/time_examples.mdc` for practical examples and patterns
|
|
|
|
**Status**: Active time handling guidelines
|
|
**Priority**: High
|
|
**Estimated Effort**: Ongoing reference
|
|
**Dependencies**: None
|
|
**Stakeholders**: Development team, Documentation team
|
|
|
|
**Maintainer**: Matthew Raymer
|
|
**Next Review**: 2025-09-17
|
|
|
|
## Model Implementation Checklist
|
|
|
|
### Before Time-Related Work
|
|
|
|
- [ ] **Time Context**: Understand what time information is needed
|
|
- [ ] **Format Review**: Review time formatting standards (UTC, ISO 8601)
|
|
- [ ] **Platform Check**: Identify platform-specific time requirements
|
|
- [ ] **User Context**: Consider user's timezone and preferences
|
|
|
|
### During Time Implementation
|
|
|
|
- [ ] **UTC Usage**: 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
|
|
|
|
- [ ] **Validation**: Verify time formats are correct and consistent
|
|
- [ ] **Testing**: Test time handling across different scenarios
|
|
- [ ] **Documentation**: Update relevant documentation with time patterns
|
|
- [ ] **Review**: Confirm implementation follows time standards
|
|
|