--- a/doc/upgrade.txt
+++ b/doc/upgrade.txt
@@ -30,6 +30,18 @@
 warned that lenient error handling may be removed completely in a
 future release.
 
+There has also been a subtle change to how ``py:match`` templates are
+processed: in previous versions, all match templates would be applied
+to the content generated by the matching template, and only the
+matching template itself was applied recursively to the original
+content. This behavior resulted in problems with many kinds of
+recursive matching, and hence was changed for 0.5: now, all match
+templates declared before the matching template are applied to the
+original content, and match templates declared after the matching
+template are applied to the generated content. This change should not
+have any effect on most applications, but you may want to check your
+use of match templates to make sure.
+
 
 Upgrading from Genshi 0.3.x to 0.4.x
 ------------------------------------