document necessary tests

pep-0487.txt

@@ -297,6 +297,54 @@ replace the current ``type`` and ``object`` with the following::
             pass
 
 
+Backward compatibility issues
+=============================
+
+The exact calling sequence in ``type.__new__`` is slightly changed, raising
+fears of backwards compatibility. It should be assured by tests that common use
+cases behave as desirerd.
+
+The following class definitions (except the one defining the metaclass)
+continue to fail with a ``TypeError`` as superfluous class arguments are passed::
+
+    class MyMeta(type):
+        pass
+
+    class MyClass(metaclass=MyMeta, otherarg=1):
+        pass
+
+    MyMeta("MyClass", (), otherargs=1)
+
+    import types
+    types.new_class("MyClass", (), dict(metaclass=MyMeta, otherarg=1))
+    types.prepare_class("MyClass", (), dict(metaclass=MyMeta, otherarg=1))
+
+A metaclass defining only a ``__new__`` method which is interested in keyword
+arguments now does not need to define an ``__init__`` method anymore, as the
+default ``type.__init__`` ignores keyword arguments. This is nicely in line
+with the recommendation to override ``__new__`` in metaclasses instead of
+``__init__``. The following code does not fail anymore::
+
+    class MyMeta(type):
+        def __new__(cls, name, bases, namespace, otherarg):
+            return super().__new__(cls, name, bases, namespace)
+
+    class MyClass(metaclass=MyMeta, otherarg=1):
+        pass
+
+Only defining a ``__init__`` in a metaclass continues to fail with ``TypeError``
+if keyword arguments are given::
+
+    class MyMeta(type):
+        def __init__(self, name, bases, namespace, otherarg):
+            super().__init__(name, bases, namespace)
+
+    class MyClass(metaclass=MyMeta, otherarg=1):
+        pass
+
+Defining both ``__init__`` and ``__new__`` continues to work fine.
+
+
 Rejected Design Options
 =======================