Fixed #32379 -- Started deprecation toward changing default USE_TZ to True.

Co-authored-by: Nick Pope <nick@nickpope.me.uk>
Co-authored-by: Mariusz Felisiak <felisiak.mariusz@gmail.com>

7 files changed, 60 insertions, 5 deletions

diff --git a/django/conf/__init__.py b/django/conf/__init__.py
index 00b2ab82d0..628b1f7e4d 100644
--- a/django/conf/__init__.py
+++ b/django/conf/__init__.py
@@ -9,10 +9,12 @@ for a list of all possible variables.
 import importlib
 import os
 import time
+import warnings
 from pathlib import Path
 
 from django.conf import global_settings
 from django.core.exceptions import ImproperlyConfigured
+from django.utils.deprecation import RemovedInDjango50Warning
 from django.utils.functional import LazyObject, empty
 
 ENVIRONMENT_VARIABLE = "DJANGO_SETTINGS_MODULE"
@@ -157,6 +159,14 @@ class Settings:
                 setattr(self, setting, setting_value)
                 self._explicit_settings.add(setting)
 
+        if self.USE_TZ is False and not self.is_overridden('USE_TZ'):
+            warnings.warn(
+                'The default value of USE_TZ will change from False to True '
+                'in Django 5.0. Set USE_TZ to False in your project settings '
+                'if you want to keep the current default behavior.',
+                category=RemovedInDjango50Warning,
+            )
+
         if hasattr(time, 'tzset') and self.TIME_ZONE:
             # When we can, attempt to validate the timezone. If we can't find
             # this file, no check happens and it's harmless.
diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index da15e4871e..1b5eb35769 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -21,6 +21,9 @@ details on these changes.
 
 * The undocumented ``django.utils.datetime_safe`` module will be removed.
 
+* The default value of the ``USE_TZ`` setting will change from ``False`` to
+  ``True``.
+
 .. _deprecation-removed-in-4.1:
 
 4.1
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index 6a568ea9b7..e6eee7d6bb 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -2809,6 +2809,10 @@ See also :setting:`DECIMAL_SEPARATOR`, :setting:`NUMBER_GROUPING` and
 
 Default: ``False``
 
+.. note::
+
+    In Django 5.0, the default value will change from ``False`` to ``True``.
+
 A boolean that specifies if datetimes will be timezone-aware by default or not.
 If this is set to ``True``, Django will use timezone-aware datetimes internally.
 
diff --git a/docs/releases/4.0.txt b/docs/releases/4.0.txt
index 3168200070..207c6af5f6 100644
--- a/docs/releases/4.0.txt
+++ b/docs/releases/4.0.txt
@@ -431,6 +431,20 @@ Miscellaneous
 Features deprecated in 4.0
 ==========================
 
+Time zone support
+-----------------
+
+In order to follow good practice, the default value of the :setting:`USE_TZ`
+setting will change from ``False`` to ``True``, and time zone support will be
+enabled by default, in Django 5.0.
+
+Note that the default :file:`settings.py` file created by
+:djadmin:`django-admin startproject <startproject>` includes
+:setting:`USE_TZ = True <USE_TZ>` since Django 1.4.
+
+You can set ``USE_TZ`` to ``False`` in your project settings before then to
+opt-out.
+
 Miscellaneous
 -------------
 
diff --git a/docs/topics/i18n/timezones.txt b/docs/topics/i18n/timezones.txt
index e95b7a29de..7517ae47fc 100644
--- a/docs/topics/i18n/timezones.txt
+++ b/docs/topics/i18n/timezones.txt
@@ -26,11 +26,16 @@ to this problem is to use UTC in the code and use local time only when
 interacting with end users.
 
 Time zone support is disabled by default. To enable it, set :setting:`USE_TZ =
-True <USE_TZ>` in your settings file. By default, time zone support uses pytz_,
-which is installed when you install Django; Django also supports the use of
-other time zone implementations like :mod:`zoneinfo` by passing
-:class:`~datetime.tzinfo` objects directly to functions in
-:mod:`django.utils.timezone`.
+True <USE_TZ>` in your settings file.
+
+.. note::
+
+    In Django 5.0, time zone support will be enabled by default.
+
+By default, time zone support uses pytz_, which is installed when you install
+Django; Django also supports the use of other time zone implementations like
+:mod:`zoneinfo` by passing :class:`~datetime.tzinfo` objects directly to
+functions in :mod:`django.utils.timezone`.
 
 .. versionchanged:: 3.2
 
diff --git a/tests/settings_tests/tests.py b/tests/settings_tests/tests.py
index c0c53fe391..ba38fd87ba 100644
--- a/tests/settings_tests/tests.py
+++ b/tests/settings_tests/tests.py
@@ -13,6 +13,7 @@ from django.test import (
 )
 from django.test.utils import requires_tz_support
 from django.urls import clear_script_prefix, set_script_prefix
+from django.utils.deprecation import RemovedInDjango50Warning
 
 
 @modify_settings(ITEMS={
@@ -332,6 +333,21 @@ class SettingsTests(SimpleTestCase):
         with self.assertRaisesMessage(ValueError, 'Incorrect timezone setting: test'):
             settings._setup()
 
+    def test_use_tz_false_deprecation(self):
+        settings_module = ModuleType('fake_settings_module')
+        settings_module.SECRET_KEY = 'foo'
+        sys.modules['fake_settings_module'] = settings_module
+        msg = (
+            'The default value of USE_TZ will change from False to True in '
+            'Django 5.0. Set USE_TZ to False in your project settings if you '
+            'want to keep the current default behavior.'
+        )
+        try:
+            with self.assertRaisesMessage(RemovedInDjango50Warning, msg):
+                Settings('fake_settings_module')
+        finally:
+            del sys.modules['fake_settings_module']
+
 
 class TestComplexSettingOverride(SimpleTestCase):
     def setUp(self):
@@ -398,6 +414,7 @@ class IsOverriddenTest(SimpleTestCase):
     def test_module(self):
         settings_module = ModuleType('fake_settings_module')
         settings_module.SECRET_KEY = 'foo'
+        settings_module.USE_TZ = False
         sys.modules['fake_settings_module'] = settings_module
         try:
             s = Settings('fake_settings_module')
diff --git a/tests/test_sqlite.py b/tests/test_sqlite.py
index 099f37e56d..e1252f5f7d 100644
--- a/tests/test_sqlite.py
+++ b/tests/test_sqlite.py
@@ -29,3 +29,5 @@ PASSWORD_HASHERS = [
 ]
 
 DEFAULT_AUTO_FIELD = 'django.db.models.AutoField'
+
+USE_TZ = False