Fixed #29817 -- Deprecated settings.FILE_CHARSET.

6 files changed, 18 insertions, 11 deletions

diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index 1d03648ab1..4a40300442 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -24,6 +24,8 @@ details on these changes.
 * ``django.contrib.postgres.fields.FloatRangeField`` and
   ``django.contrib.postgres.forms.FloatRangeField`` will be removed.
 
+* The ``FILE_CHARSET`` setting will be removed.
+
 .. _deprecation-removed-in-3.0:
 
 3.0
diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt
index 1a3baecfda..1323d1292c 100644
--- a/docs/ref/django-admin.txt
+++ b/docs/ref/django-admin.txt
@@ -613,8 +613,7 @@ the :ref:`i18n documentation <how-to-create-language-files>` for details.
 
 This command doesn't require configured settings. However, when settings aren't
 configured, the command can't ignore the :setting:`MEDIA_ROOT` and
-:setting:`STATIC_ROOT` directories or include :setting:`LOCALE_PATHS`. It will
-also write files in UTF-8 rather than in :setting:`FILE_CHARSET`.
+:setting:`STATIC_ROOT` directories or include :setting:`LOCALE_PATHS`.
 
 .. django-admin-option:: --all, -a
 
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index ef00d19b1b..cc2892077b 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -1424,7 +1424,12 @@ attempt.
 Default: ``'utf-8'``
 
 The character encoding used to decode any files read from disk. This includes
-template files and initial SQL data files.
+template files, static files, and translation catalogs.
+
+.. deprecated:: 2.2
+
+    This setting is deprecated. Starting with Django 3.1, files read from disk
+    must be UTF-8 encoded.
 
 .. setting:: FILE_UPLOAD_HANDLERS
 
@@ -3374,7 +3379,6 @@ Error reporting
 File uploads
 ------------
 * :setting:`DEFAULT_FILE_STORAGE`
-* :setting:`FILE_CHARSET`
 * :setting:`FILE_UPLOAD_HANDLERS`
 * :setting:`FILE_UPLOAD_MAX_MEMORY_SIZE`
 * :setting:`FILE_UPLOAD_PERMISSIONS`
diff --git a/docs/ref/unicode.txt b/docs/ref/unicode.txt
index 0b0282b1cc..8617442318 100644
--- a/docs/ref/unicode.txt
+++ b/docs/ref/unicode.txt
@@ -265,12 +265,11 @@ Use strings when creating templates manually::
     from django.template import Template
     t2 = Template('This is a string template.')
 
-But the common case is to read templates from the filesystem, and this creates
-a slight complication: not all filesystems store their data encoded as UTF-8.
-If your template files are not stored with a UTF-8 encoding, set the :setting:`FILE_CHARSET`
-setting to the encoding of the files on disk. When Django reads in a template
-file, it will convert the data from this encoding to Unicode. (:setting:`FILE_CHARSET`
-is set to ``'utf-8'`` by default.)
+But the common case is to read templates from the filesystem. If your template
+files are not stored with a UTF-8 encoding, adjust the :setting:`TEMPLATES`
+setting. The built-in :py:mod:`~django.template.backends.django` backend
+provides the ``'file_charset'`` option to change the encoding used to read
+files from disk.
 
 The :setting:`DEFAULT_CHARSET` setting controls the encoding of rendered templates.
 This is set to UTF-8 by default.
diff --git a/docs/releases/2.2.txt b/docs/releases/2.2.txt
index 22d7eee0c1..e8f20f6836 100644
--- a/docs/releases/2.2.txt
+++ b/docs/releases/2.2.txt
@@ -332,3 +332,6 @@ Miscellaneous
 * The ``FloatRangeField`` model and form fields in ``django.contrib.postgres``
   are deprecated in favor of a new name, ``DecimalRangeField``, to match the
   underlying ``numrange`` data type used in the database.
+
+* The ``FILE_CHARSET`` setting is deprecated. Starting with Django 3.1, files
+  read from disk must be UTF-8 encoded.
diff --git a/docs/topics/templates.txt b/docs/topics/templates.txt
index 297008668f..c3f9a6b5eb 100644
--- a/docs/topics/templates.txt
+++ b/docs/topics/templates.txt
@@ -351,7 +351,7 @@ applications. This generic name was kept for backwards-compatibility.
 
 * ``'file_charset'``: the charset used to read template files on disk.
 
-  It defaults to the value of :setting:`FILE_CHARSET`.
+  It defaults to ``'utf-8'``.
 
 * ``'libraries'``: A dictionary of labels and dotted Python paths of template
   tag modules to register with the template engine. This can be used to add