Add common issue docs for PEP584 syntax upgrade

As discussed with @AlexWaygood in
#14245 (comment)
adding a common issue entry for the problem of hitting overshadowing a
built-in keyword when upgrading to PEP584 syntax

Author: LefterisJP

docs/source/common_issues.rst

@@ -821,3 +821,55 @@ This is best understood via an example:
 To get this code to type check, you could assign ``y = x`` after ``x`` has been
 narrowed, and use ``y`` in the inner function, or add an assert in the inner
 function.
+
+
+Upgrading to :pep:`585` syntax
+------------------------------
+
+In pre-:pep:`585` syntax type annotations for builtin types such as ``dict``,
+``list``, ``tuple``, ``type`` were taken from the :py:mod:`typing` module as
+``typing.Dict``, ``typing.List``, ``typing.Tuple``, ``typing.Type`` etc.
+
+When updating a codebase to use modern syntax, you may hit a case such as the following:
+
+.. code-block:: python
+
+    from typing import TypeVar
+
+    T = TypeVar("T", bound="Foo")
+
+    class Foo:
+	type: str
+
+	@classmethod
+	def bar(cls: type[T], value: str) -> None:
+	    pass    # Mypy complains that "Foo.type" is "not valid as a type"
+
+This occurs due to the fact that the class has an attribute named `type`
+that shadows the built-in function :py:func:`type`.
+To illustrate the issue: at runtime in the following example,
+the annotation for `arg` in the `ham` method
+is resolved as being the string `"spam"`
+due to the fact that method signatures are executed
+in the same scope as class attributes:
+
+.. code-block:: pycon
+
+    >>> class Eggs:
+    ...     type: str = "spam"
+    ...     def ham(self, arg: type) -> None:
+    ...         pass
+    ...
+    >>> import inspect
+    >>> inspect.signature(Eggs.ham)
+    <Signature (self, arg: 'spam') -> None>
+
+Mypy follows the same scoping semantics as Python at runtime
+when resolving references.
+To get this code to type-check, therefore, you have the following options:
+
+- Continue using  ``typing.Type[]`` for your annotation.
+- Add ``import builtins`` to the top of your module and use ``builtins.type[]`` for your annotation.
+- Add ``from builtins import type as Type`` to the top of your module and use ``Type[]`` for your annotation
+
+The same thing applies for any other built-in name.