porting guide 2.19 - describe lazy complex var eval impact on builtin filters/tests (#2639) (#2851)

* porting guide 2.19 - describe lazy complex variable evaluation impact for common Jinja2 filters/tests

* remove unlikely example

* Fix terminology

* dnaro suggestion: add comments

* Update docs/docsite/rst/porting_guides/porting_guide_core_2.19.rst



* Update docs/docsite/rst/porting_guides/porting_guide_core_2.19.rst



* Update docs/docsite/rst/porting_guides/porting_guide_core_2.19.rst



* Update docs/docsite/rst/porting_guides/porting_guide_core_2.19.rst



* Remove 'embedded template' phrasing and remove quotation marks around variable for consistency with other comments

---------



(cherry picked from commit 2c0cb48)

Co-authored-by: Sloane Hertel <[email protected]>
Co-authored-by: Don Naro <[email protected]>
Co-authored-by: Felix Fontein <[email protected]>

Author: 4 people

docs/docsite/rst/porting_guides/porting_guide_core_2.19.rst

@@ -782,6 +782,32 @@ Noteworthy plugin changes
   This filter now returns ``False`` instead of ``None`` when the input is ``None``.
   The aforementioned deprecation warning is also issued in this case.
 
+* Passing nested non-scalars with embedded templates that may resolve to ``Undefined`` to Jinja2
+  filter plugins, such as ``default`` and ``mandatory``, and test plugins including ``defined`` and ``undefined``
+  no longer evaluate as they did in previous versions because nested non-scalars with embedded templates are templated
+  on use only.
+  In 2.19, this assertion passes:
+
+  .. code-block:: yaml
+
+     - assert:
+         that:
+           # Unlike earlier versions, complex_var is defined even though complex_var.nested is not.
+           - complex_var is defined
+           # Unlike earlier versions, the default value is not applied because complex_var is defined.
+           - (complex_var | default(unused)).nested is undefined
+           # Like earlier versions, directly accessing complex_var.nested evaluates as undefined.
+           - complex_var.nested is undefined
+       vars:
+         complex_var:
+           # Before 2.19, complex_var.nested is evaluated immediately when complex_var is accessed.
+           # In 2.19, complex_var.nested is evaluated only when it is accessed.
+           nested: "{{ undefined_variable }}"
+         unused:
+           # This variable is used only if complex_var is undefined.
+           # This only happens in ansible-core before 2.19.
+           nested: default
+
 
 Porting custom scripts
 ======================