Document 1.1 timestamp normalization behavior (#815)

* Document 1.1 timestamp normalization

* Fix spelling in 1.1 docs

Author: abrookins

docs/migrations.md

@@ -217,6 +217,34 @@ Redis OM includes a built-in migration for datetime field indexing improvements.
 
 For detailed information about this migration, see the **[0.x to 1.0 Migration Guide](migration_guide_0x_to_1x.md#datetime-migration-details)**.
 
+### Datetime Timezone Normalization in 1.1.0
+
+Redis OM Python 1.1.0 tightens timestamp handling for both `datetime.datetime` and `datetime.date` fields:
+
+- `datetime.datetime` values are read back as **UTC-aware** `datetime` values.
+- `datetime.date` values are stored as **midnight UTC** instead of local-midnight timestamps.
+
+This is usually what you want, but it matters if you already have data written by versions before 1.1.0:
+
+- Older `datetime.datetime` records still represent the same instant in time, but code that expected naive `datetime` values may need to handle UTC-aware values.
+- Older `datetime.date` records written in a **non-UTC** environment may load as a different calendar day after upgrading, and equality queries may stop matching those records.
+
+If you have existing `datetime.date` data from a release before 1.1.0 and your application was not running in UTC, plan to migrate or re-save that data after upgrading.
+
+Example symptom after upgrade:
+
+- Stored before 1.1.0 in `Asia/Karachi`: `date(2023, 1, 1)` -> `1672513200` (local midnight)
+- Stored in 1.1.0+: `date(2023, 1, 1)` -> `1672531200` (midnight UTC)
+
+If your application relies on date equality queries, verify old records after upgrading:
+
+```bash
+# Spot-check records after upgrading
+om migrate-data status
+```
+
+If needed, create a custom data migration to normalize affected `datetime.date` fields by re-saving them with Redis OM 1.1.0+.
+
 ## Advanced Usage
 
 ### Module-Based Migrations

docs/release_notes_1.1.md

@@ -0,0 +1,19 @@
+# Redis OM Python 1.1 Release Notes
+
+Redis OM Python 1.1 focuses on compatibility updates and timestamp normalization fixes.
+
+## Notable Changes
+
+- RedisVL dependency updated to allow newer Python versions
+- `datetime.datetime` values now round-trip as UTC-aware `datetime` values
+- `datetime.date` values now store as midnight UTC instead of local-midnight timestamps
+
+## Timestamp Upgrade Note
+
+The timestamp normalization change is important if you already have data written by earlier releases:
+
+- Existing `datetime.datetime` records still represent the same instant in time, but code that expected naive `datetime` values may need to handle UTC-aware values.
+- Existing `datetime.date` records written in a non-UTC environment may load as a different calendar day after upgrading.
+- Date equality queries may stop matching those older records until the data is re-saved or migrated.
+
+For migration guidance, see [Migrations: Datetime Timezone Normalization in 1.1.0](migrations.md#datetime-timezone-normalization-in-110).

mkdocs.yml

@@ -72,6 +72,7 @@ nav:
   - Reference:
       - Errors: errors.md
       - Release Notes 1.0: release_notes_1.0.md
+      - Release Notes 1.1: release_notes_1.1.md
       - Upgrade Guide (0.x → 1.x): migration_guide_0x_to_1x.md
 
 plugins:
@@ -105,4 +106,3 @@ extra_css:
 
 copyright: |
   &copy; 2024 <a href="https://github.com/redis" target="_blank" rel="noopener">Redis</a>
-