--- a/UPGRADE.txt
+++ b/UPGRADE.txt
@@ -1,6 +1,20 @@
 Upgrading Genshi
 ================
 
+Upgrading from Genshi 0.4.x to 0.5.x
+------------------------------------
+
+Genshi 0.5 introduces a new, alternative syntax for text templates, which is
+more flexible and powerful compared to the old syntax. For backwards
+compatibility, this new syntax is not used by default, though it will be in
+a future version. It is recommended that you migrate to using this new syntax.
+To do so, simply rename any references in your code to `TextTemplate` to
+`NewTextTemplate`. To explicitly use the old syntax, use `OldTextTemplate`
+instead, so that you can be sure you'll be using the same language when the
+default in Genshi is changed (at least until the old implementation is
+completely removed).
+
+
 Upgrading from Genshi 0.3.x to 0.4.x
 ------------------------------------