Fixed #25968 -- Changed project/app templates to use a "py-tpl" suffix.

Debian packages unconditionally byte-compile .py files on installation and
do not silence errors by design. Therefore, we need a way of shipping these
invalid .py files without a .py extension but ensuring that when we
template them, they end up as .py.

We don't special-case .py files so that the all the TemplateCommand
command-line options (eg. extra_files and extensions) still work entirely
as expected and it may even be useful for other formats too.

4 files changed, 31 insertions, 5 deletions

diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt
index a0d9e54296..5bc31ea112 100644
--- a/docs/ref/django-admin.txt
+++ b/docs/ref/django-admin.txt
@@ -1175,6 +1175,15 @@ files is:
     To work around this problem, you can use the :ttag:`templatetag`
     templatetag to "escape" the various parts of the template syntax.
 
+    In addition, to allow Python template files that contain Django template
+    language syntax while also preventing packaging systems from trying to
+    byte-compile invalid ``*.py`` files, template files ending with ``.py-tpl``
+    will be renamed to ``.py``.
+
+    .. versionchanged:: 1.9.2
+
+        Renaming of ``.py-tpl`` to ``.py`` was added.
+
 .. _source: https://github.com/django/django/tree/master/django/conf/app_template/
 
 startproject
diff --git a/docs/releases/1.9.2.txt b/docs/releases/1.9.2.txt
index f977b02ac3..e64c62e3da 100644
--- a/docs/releases/1.9.2.txt
+++ b/docs/releases/1.9.2.txt
@@ -4,7 +4,24 @@ Django 1.9.2 release notes
 
 *Under development*
 
-Django 1.9.2 fixes several bugs in 1.9.1.
+Django 1.9.2 fixes several bugs in 1.9.1 and makes a small backwards
+incompatible change that hopefully doesn't affect any users.
+
+Backwards incompatible change: ``.py-tpl`` files rewritten in project/app templates
+===================================================================================
+
+The addition of some Django template language syntax to the default app
+template in Django 1.9 means those files now have some invalid Python syntax.
+This causes difficulties for packaging systems that unconditionally
+byte-compile ``*.py`` files.
+
+To remedy this, a ``.py-tpl`` suffix is now used for the project and app
+template files included in Django. The ``.py-tpl`` suffix is replaced with
+``.py`` by the ``startproject`` and ``startapp`` commands. For example, a
+template with the filename ``manage.py-tpl`` will be created as ``manage.py``.
+
+Please file a ticket if you have a custom project template containing
+``.py-tpl`` files and find this behavior problematic.
 
 Bugfixes
 ========
diff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt
index dc43dce873..0c67558d69 100644
--- a/docs/releases/1.9.txt
+++ b/docs/releases/1.9.txt
@@ -1017,7 +1017,7 @@ a Django application with this structure::
 ``SyntaxError`` when installing Django setuptools 5.5.x
 -------------------------------------------------------
 
-When installing Django 1.9+ with setuptools 5.5.x, you'll see::
+When installing Django 1.9 or 1.9.1 with setuptools 5.5.x, you'll see::
 
     Compiling django/conf/app_template/apps.py ...
       File "django/conf/app_template/apps.py", line 4
@@ -1034,7 +1034,8 @@ When installing Django 1.9+ with setuptools 5.5.x, you'll see::
 It's safe to ignore these errors (Django will still install just fine), but you
 can avoid them by upgrading setuptools to a more recent version. If you're
 using pip, you can upgrade pip using ``pip install -U pip`` which will also
-upgrade setuptools.
+upgrade setuptools. This is resolved in later versions of Django as described
+in the :doc:`/releases/1.9.2`.
 
 Miscellaneous
 -------------
diff --git a/docs/topics/install.txt b/docs/topics/install.txt
index f0fbc47881..b5195bea57 100644
--- a/docs/topics/install.txt
+++ b/docs/topics/install.txt
@@ -165,8 +165,7 @@ This is the recommended way to install Django.
 1. Install pip_. The easiest is to use the `standalone pip installer`_. If your
    distribution already has ``pip`` installed, you might need to update it if
    it's outdated. If it's outdated, you'll know because installation won't
-   work. If you're using an old version of setuptools, you might see some
-   :ref:`harmless SyntaxErrors <syntax-error-old-setuptools-django-19>` also.
+   work.
 
 2. Take a look at virtualenv_ and virtualenvwrapper_. These tools provide
    isolated Python environments, which are more practical than installing