From 8863a680f5e0d47f1967ba6ba1858d960926b19e Mon Sep 17 00:00:00 2001
From: Ronnie Dutta <61982285+MetRonnie@users.noreply.github.com>
Date: Fri, 17 Jul 2026 17:43:35 +0100
Subject: [PATCH] Add changelog for jinja2 warnings

---
 src/reference/changes.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/src/reference/changes.rst b/src/reference/changes.rst
index 0332561609..62167ff3cc 100644
--- a/src/reference/changes.rst
+++ b/src/reference/changes.rst
@@ -19,6 +19,23 @@ Cylc 8.6
    :rose: `2.6 <https://github.com/metomi/rose/blob/2.6.x/CHANGES.md>`__
 
 
+Warnings during Jinja2 preprocessing
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: cylc-flow 8.6.6
+
+Python warnings raised during Jinja2 preprocessing are now logged when running
+relevant Cylc commands (e.g. ``cylc validate`` and ``cylc play``).
+
+.. warning::
+
+   Cylc 8.7.0 will move from Jinja2 3.0 to 3.1, which removes a number of
+   deprecated features.
+   This should only affect you if you use :ref:`CustomJinja2Filters`.
+   Warnings for these deprecations are now logged, but were not previously.
+   See the `Jinja 3.1 release notes <https://jinja.palletsprojects.com/en/stable/changes/#version-3-1-0>`_.
+
+
 UI sidebar improvements
 ^^^^^^^^^^^^^^^^^^^^^^^