doc: incompat

sphinx/source/incompatible.rst

@@ -197,6 +197,34 @@ To disable this, add to your game::
 
     define config.screens_never_cancel_hide = False
 
+**How ATL sets the child from parameters** The rules as for how and when ATL
+transforms get their child set, based upon the parameters they accept and the
+arguments they are passed, has slightly changed. It is unlikely to have any
+impact on existing games, especially if you were only using documented features.
+
+- The `old_widget` parameter taking a value from a positional argument does not
+  set the child anymore. That was not documented. ::
+
+    transform t(old_widget):
+        ...
+
+    t("eileen") # will no longer have a child set to the "eileen" image
+
+- A `child` keyword argument being passed to a transform having a `child`
+  parameter now sets the child, just as it would in a transform with no
+  `child` parameter, or if the `child` parameter got a value from a positional
+  argument. The documentation was ambiguous about this. ::
+
+    transform t1(child):
+        ...
+
+    transform t2(chile):
+        ...
+
+    t1(child="eileen") # will now have a child set to the "eileen" image, but previously didn't
+    t2(child="eileen") # the child is set, as before
+    t1("eileen") # the child is set, as before
+
 
 .. _incompatible-8.1.1:
 .. _incompatible-7.6.1: