Update CHANGELOG and docs

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

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 = [])
     {