Better error message if the template is not utf-8 encoded (#41030)

* Better error message if the template is not utf-8 encoded

Also document this in the porting guide
(cherry picked from commit cef4d862bc)

docs/docsite/rst/porting_guides/porting_guide_2.5.rst

@@ -202,6 +202,12 @@ desired.
   * The :ref:`blockinfile module <blockinfile_module>` had its ``follow`` parameter removed because
     it inherently modifies the content of an existing file so it makes no sense to operate on the
     link itself.
+  * In Ansible-2.5.3, the :ref:`template module <template_module>` became more strict about its
+    ``src`` file being proper utf-8.  Previously, non-utf8 contents in a template module src file
+    would result in a mangled output file (the non-utf8 characters would be replaced with a unicode
+    replacement character).  Now, on Python2, the module will error out with the message, "Template
+    source files must be utf-8 encoded".  On Python3, the module will first attempt to pass the
+    non-utf8 characters through verbatim and fail if that does not succeed.
 
 Plugins
 =======

lib/ansible/plugins/action/template.py

@@ -120,7 +120,10 @@ class ActionModule(ActionBase):
             # template the source data locally & get ready to transfer
             try:
                 with open(b_tmp_source, 'rb') as f:
+                    try:
                         template_data = to_text(f.read(), errors='surrogate_or_strict')
+                    except UnicodeError:
+                        raise AnsibleActionFail("Template source files must be utf-8 encoded")
 
                 # set jinja2 internal search path for includes
                 searchpath = task_vars.get('ansible_search_path', [])