002 timestamp timezone handling

ADR 002: Timestamp Timezone Handling

Status

• Status: Proposed
• Date: 2025-01-13

Context

The Dev Notes CLI tool currently has an inconsistency in its timestamp handling:

1. File Names: Uses UTC (toISOString())

   • Example: 2025-01-13_slack communication.md (UTC date)
   • Can show "next day" for evening hours in negative UTC offset zones

2. Content Timestamp: Uses local time

   • Example: Created: 2025-01-13 18:52:49 (local time)
   • Matches user's local expectations

This distinction between filename and content timestamps is a crucial detail I missed in the original draft. It makes the need for standardization even more apparent since we currently have mixed timezone handling within the same note. For example, at 6:52 PM CST:

• Filename: 2025-01-14_example.md (UTC already rolled to next day)
• Content: Created: 2025-01-13 18:52:49 (local CST time)

We have two potential approaches:

Approach 1: Local Timezone

• Use toLocaleDateString() and toLocaleTimeString()
• Filenames and timestamps match user's local expectations
• Different users see different timestamps for same moment

Approach 2: UTC Standardization

• Keep current UTC approach
• Add explicit UTC indicator in timestamps
• Document timezone handling clearly
• Consider showing local time alongside UTC

Decision Drivers

• User experience and intuitive behavior
• Cross-timezone collaboration needs
• Git commit history alignment
• File sorting consistency

Open Questions

1. How important is cross-timezone collaboration?
2. Should filenames match local time while content timestamps use UTC?
3. Do we need to support timezone-aware searching/filtering?

Notes

This impacts both user experience and potential future features like note synchronization or collaborative editing.

Decision

• Date: [TBD]
• Chosen Approach: [TBD]

Rationale

[To be filled after decision]

Consequences

Approach 1 (Local) Consequences

Positive:

• Intuitive timestamps for single-user scenarios
• Filenames match user's workday
• Simpler mental model for local users

Negative:

• Potential sorting inconsistencies across timezones
• Harder to determine exact moment in collaborative scenarios
• May complicate future sync features

Approach 2 (UTC) Consequences

Positive:

• Consistent ordering across all timezones
• Unambiguous timestamps for collaboration
• Aligns with Git timestamp handling

Negative:

• Counter-intuitive file dating for evening work
• Requires users to think in UTC
• May need additional local time display

Implementation Notes

Implementation considerations:

1. Date/time formatting consistency
2. Migration strategy for existing notes
3. Configuration options for timestamp display
4. Documentation updates