diff --git a/CHANGELOG b/CHANGELOG
index 8770369b4d6..fa50ff1e5ea 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -1,5 +1,7 @@
 # 3.12.0 (2024-XX-XX)
 
+ * Fix performance regression when `use_yield` is `false` (which is the default)
+ * Improve compatibility when `use_yield` is `false` (as extensions still using `echo` will work as is)
  * Accept colons (`:`) in addition to equals (`=`) to separate argument names and values in named arguments
  * Add the `html_cva` function (in the HTML extra package)
  * Add support for named arguments to the `block` and `attribute` functions
diff --git a/src/Environment.php b/src/Environment.php
index 96bf8afbdb1..237d598032a 100644
--- a/src/Environment.php
+++ b/src/Environment.php
@@ -103,9 +103,9 @@ class Environment
      *                   (default to -1 which means that all optimizations are enabled;
      *                   set it to 0 to disable).
      *
-     *  * use_yield: Enable templates to exclusively use "yield" instead of "echo"
-     *               (default to "false", but switch it to "true" when possible
-     *               as this will be the only supported mode in Twig 4.0)
+     *  * use_yield: true: forces templates to exclusively use "yield" instead of "echo" (all extensions must be yield ready)
+     *               false (default): allows templates to use a mix of "yield" and "echo" calls to allow for a progressive migration
+     *               Switch to "true" when possible as this will be the only supported mode in Twig 4.0
      */
     public function __construct(LoaderInterface $loader, $options = [])
     {