From 1205b8b6ca4b328dd0eb01975eab6a834d5d8e8e Mon Sep 17 00:00:00 2001
From: Fabien Potencier <fabien@potencier.org>
Date: Thu, 27 Aug 2026 13:07:26 +0200
Subject: [PATCH] Document that overriding MacroNode::compile() is not
 supported anymore

---
 doc/deprecated.rst | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/doc/deprecated.rst b/doc/deprecated.rst
index 703dfed5f..668343c27 100644
--- a/doc/deprecated.rst
+++ b/doc/deprecated.rst
@@ -12,7 +12,10 @@ Classes
   final in Twig 4.0. Use ``Twig\Markup`` directly instead of extending it.
 
 * The ``Twig\Node\MacroNode`` class is considered final as of Twig 3.29 and
-  will be final in Twig 4.0.
+  will be final in Twig 4.0. Note that macros are compiled as closures stored
+  in a per-template registry as of Twig 3.29, so overriding
+  ``MacroNode::compile()`` based on the previous contract (emitting a
+  ``macro_``-prefixed method) is not supported anymore.
 
 Functions
 ---------