docs: add notes about DateTime value handling

docs/conf.py

@@ -9,7 +9,7 @@
 from importlib.metadata import version as get_version
 
 project = "WuttJamaican"
-copyright = "2023-2024, Lance Edgar"
+copyright = "2023-2025, Lance Edgar"
 author = "Lance Edgar"
 release = get_version("WuttJamaican")
 

docs/narr/db/app.rst

@@ -181,6 +181,32 @@ config.
 But if the migration went okay then you now have a complete app database.
 
 
+Notes on DateTime
+~~~~~~~~~~~~~~~~~
+
+Most data types are straightforward, but ``DateTime`` deserves some
+explanation:
+
+All built-in model definitions use a "simple"
+:class:`sqlalchemy:sqlalchemy.types.DateTime` column type, where
+relevant
+(e.g. :attr:`wuttjamaican.db.model.upgrades.Upgrade.created`).
+
+Logic expects all values for such columns to be naive
+:class:`python:datetime.datetime` instances, i.e. with no
+:attr:`~python:datetime.datetime.tzinfo` set.  However the values are
+*assumed* to be local to the UTC timezone (as though ``tzinfo`` was
+set to :attr:`~python:datetime.timezone.utc`).
+
+Auto-populating such columns when writing records is done via the
+:func:`~wuttjamaican.util.make_utc()` function.
+
+It is further assumed that custom app / extension models will follow
+similar conventions.  You should also use
+:func:`~wuttjamaican.util.make_utc()` as needed, to coerce values for
+ad-hoc writing to the DB.
+
+
 Multiple Databases
 ------------------