DOCS-4086: Guide to handling localtime

config/htaccess.yaml

@@ -4822,6 +4822,13 @@ outputs:
   - master
   - manual
 ---
+from: /tutorial/model-time-data
+to: /applications/data-models-applications
+code: 303
+type: redirect
+outputs:
+  - 'before-v2.4'
+---
 from: /core/multikey-index-bounds
 to: /core/indexes/
 code: 303

source/includes/toc-data-models-applications.yaml

@@ -13,4 +13,8 @@ description: |
 file: /tutorial/model-monetary-data
 description: |
    Describes two methods to model monetary data in MongoDB.
+---
+file: /tutorial/model-time-data
+description: |
+   Describes how to deal with local time in MongoDB.
 ...

source/tutorial/model-time-data.txt

@@ -0,0 +1,32 @@
+===============
+Model Time Data
+===============
+
+.. default-domain:: mongodb
+
+Overview
+--------
+
+MongoDB :ref:`stores times in UTC <document-bson-type-date>` by default, and will convert
+any local time representations into this form. Applications that must operate or
+report on some unmodified local time value may store the time zone alongside the
+UTC timestamp, and compute the original local time in their application logic.
+
+Example
+-------
+
+In the MongoDB shell, you can store both the current date and the current
+client's offset from UTC.
+
+.. code-block:: javascript
+
+   var now = new Date();
+   db.data.save( { date: now,
+                   offset: now.getTimezoneOffset() } );
+
+You can reconstruct the original local time by applying the saved offset:
+
+.. code-block:: javascript
+
+   var record = db.data.findOne();
+   var localNow = new Date( record.date.getTime() -  ( record.offset * 60000 ) );