From 0b51a14a08d87406756846702dac0c395918a424 Mon Sep 17 00:00:00 2001
From: Jeroen Versteeg <jeroen@alisqi.com>
Date: Mon, 26 Aug 2024 14:23:04 +0200
Subject: [PATCH] Add documentation for types tag and extend CHANGELOG

---
 CHANGELOG          |  1 +
 doc/tags/index.rst |  1 +
 doc/tags/types.rst | 30 ++++++++++++++++++++++++++++++
 3 files changed, 32 insertions(+)
 create mode 100644 doc/tags/types.rst

diff --git a/CHANGELOG b/CHANGELOG
index 30e00839f2c..030303da30b 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -16,6 +16,7 @@
  * Bump minimum PHP version to 8.0
  * Fix integration tests when a test has more than one data/expect section and deprecations
  * Add the `enum_cases` function
+ * Add the `types` tag
 
 # 3.11.0 (2024-08-08)
 
diff --git a/doc/tags/index.rst b/doc/tags/index.rst
index b3c10408071..692ca6094d1 100644
--- a/doc/tags/index.rst
+++ b/doc/tags/index.rst
@@ -21,6 +21,7 @@ Tags
     macro
     sandbox
     set
+    types
     use
     verbatim
     with
diff --git a/doc/tags/types.rst b/doc/tags/types.rst
new file mode 100644
index 00000000000..a487d36c5a3
--- /dev/null
+++ b/doc/tags/types.rst
@@ -0,0 +1,30 @@
+``types``
+=======
+
+The ``types`` tag declares the types for one or more names variables.
+
+To do this, specify a :ref:`mapping<twig-expressions>`) of names to their types as string constants. 
+
+Here is how you declare that variable ``foo`` is a boolean, while ``bar`` is an integer (see note below):
+
+.. code-block:: twig
+
+    {% types {
+        foo: 'bool',
+        bar: 'int',
+    } %}
+
+You may put these all on one line. However, using one line per variable improves readability.
+
+This tag has no effect on the template's output or runtime behavior.
+
+Its purpose is to enable designers and developers to document and specify the context's available
+and/or required variables.
+
+Additionally, :ref:`Twig extensions<twig-extensions>` can analyze these tags to perform compile-time and
+runtime analysis of templates in order to increase code quality.
+
+.. note::
+
+    The syntax for and contents of type strings are intentionally left out of scope. 
+