From 7a043e835506fd8e4f3eb6f50b2f35425516315d Mon Sep 17 00:00:00 2001
From: TH3CHARLie <th3charlie@gmail.com>
Date: Tue, 24 Dec 2019 13:31:51 +0800
Subject: [PATCH 1/5] update docs, add link

---
 docs/source/common_issues.rst | 41 +++++++++++++++++++++++++++++++++++
 mypy/typeanal.py              |  3 ++-
 2 files changed, 43 insertions(+), 1 deletion(-)

diff --git a/docs/source/common_issues.rst b/docs/source/common_issues.rst
index 14369e44cc56..1742e0450588 100644
--- a/docs/source/common_issues.rst
+++ b/docs/source/common_issues.rst
@@ -684,3 +684,44 @@ You can install the latest development version of mypy from source. Clone the
     git clone --recurse-submodules https://github.com/python/mypy.git
     cd mypy
     sudo python3 -m pip install --upgrade .
+
+Differentiate variables and aliases
+-----------------------------------
+
+Mypy has both type aliases and variables with types like ``Type[...]`` and it is important to know their difference.
+
+1. Variables with type ``Type[...]`` should be created by assignments with an explicit type annotations:
+
+.. code-block:: python
+
+    class A: ...
+    tp: Type[A] = A
+
+2. Aliases are created by assignments without an explicit type:
+
+.. code-block:: python
+
+    class A: ...
+    Alias = A
+
+3. The difference is that aliases are completely known statically and can be used in type context (annotations):
+
+.. code-block:: python
+
+    class A: ...
+    class B: ...
+
+    if random() > 0.5:
+        Alias = A
+    else:
+        Alias = B  # error: Cannot assign multiple types to name "Alias" without an explicit "Type[...]" annotation \
+                   # error: Incompatible types in assignment (expression has type "Type[B]", variable has type "Type[A]")
+
+    tp: Type[object]  # tp is a type variable
+    if random() > 0.5:
+        tp = A
+    else:
+        tp = B  # This is OK
+
+    def fun1(x: Alias) -> None: ...  # This is OK
+    def fun2(x: tp) -> None: ...  # error: Variable "__main__.tp" is not valid as a type
\ No newline at end of file
diff --git a/mypy/typeanal.py b/mypy/typeanal.py
index 82b4585cfafb..4f197324b610 100644
--- a/mypy/typeanal.py
+++ b/mypy/typeanal.py
@@ -423,7 +423,8 @@ def analyze_unbound_type_without_type_info(self, t: UnboundType, sym: SymbolTabl
         # TODO: Move this message building logic to messages.py.
         notes = []  # type: List[str]
         if isinstance(sym.node, Var):
-            # TODO: add a link to alias docs, see #3494.
+            notes.append('See https://mypy.readthedocs.io/en/'
+                         'latest/common_issues.html#differentiate-variables-and-aliases')
             message = 'Variable "{}" is not valid as a type'
         elif isinstance(sym.node, (SYMBOL_FUNCBASE_TYPES, Decorator)):
             message = 'Function "{}" is not valid as a type'

From ab9effd26dc64bb58e1e8e1d8666bf5431057af1 Mon Sep 17 00:00:00 2001
From: Xuanda Yang <th3charlie@gmail.com>
Date: Tue, 7 Jan 2020 10:44:20 +0800
Subject: [PATCH 2/5] automatically update author info


From 9a81de8376216502187839cc10e5b7ce67d874bf Mon Sep 17 00:00:00 2001
From: Xuanda Yang <th3charlie@gmail.com>
Date: Mon, 27 Jan 2020 23:57:11 +0800
Subject: [PATCH 3/5] fix test

---
 test-data/unit/check-columns.test       | 27 ++++++++++++++-------
 test-data/unit/check-custom-plugin.test |  3 +++
 test-data/unit/check-errorcodes.test    |  3 ++-
 test-data/unit/check-generics.test      |  6 +++--
 test-data/unit/check-literal.test       | 31 +++++++++++++++++--------
 test-data/unit/check-redefine.test      |  3 ++-
 test-data/unit/check-semanal-error.test |  1 +
 test-data/unit/check-type-aliases.test  |  6 +++--
 test-data/unit/fine-grained.test        | 10 ++++++++
 test-data/unit/merge.test               |  1 +
 test-data/unit/pythoneval-asyncio.test  |  1 +
 test-data/unit/semanal-errors.test      |  7 ++++--
 test-data/unit/semanal-typealiases.test |  6 +++--
 13 files changed, 76 insertions(+), 29 deletions(-)

diff --git a/test-data/unit/check-columns.test b/test-data/unit/check-columns.test
index 4bc70457ac29..fecf17d27482 100644
--- a/test-data/unit/check-columns.test
+++ b/test-data/unit/check-columns.test
@@ -153,16 +153,22 @@ from typing import Iterable
 
 bad = 0
 
-def f(x: bad): # E:10: Variable "__main__.bad" is not valid as a type
-    y: bad # E:8: Variable "__main__.bad" is not valid as a type
+def f(x: bad): # E:10: Variable "__main__.bad" is not valid as a type \
+               # N:10: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+    y: bad # E:8: Variable "__main__.bad" is not valid as a type \
+           # N:8: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 
 if int():
-    def g(x): # E:5: Variable "__main__.bad" is not valid as a type
+    def g(x): # E:5: Variable "__main__.bad" is not valid as a type \
+              # N:5: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
         # type: (bad) -> None
-        y = 0  # type: bad  # E:9: Variable "__main__.bad" is not valid as a type
+        y = 0  # type: bad  # E:9: Variable "__main__.bad" is not valid as a type \
+                            # N:9: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 
-z: Iterable[bad] # E:13: Variable "__main__.bad" is not valid as a type
-h: bad[int] # E:4: Variable "__main__.bad" is not valid as a type
+z: Iterable[bad] # E:13: Variable "__main__.bad" is not valid as a type \
+                 # N:13: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+h: bad[int] # E:4: Variable "__main__.bad" is not valid as a type \
+            # N:4: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 
 [case testColumnInvalidType_python2]
 
@@ -171,11 +177,14 @@ from typing import Iterable
 bad = 0
 
 if int():
-    def g(x): # E:5: Variable "__main__.bad" is not valid as a type
+    def g(x): # E:5: Variable "__main__.bad" is not valid as a type \
+              # N:5: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
         # type: (bad) -> None
-        y = 0  # type: bad  # E:9: Variable "__main__.bad" is not valid as a type
+        y = 0  # type: bad  # E:9: Variable "__main__.bad" is not valid as a type \
+                            # N:9: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 
-    z = ()  # type: Iterable[bad] # E:5: Variable "__main__.bad" is not valid as a type
+    z = ()  # type: Iterable[bad] # E:5: Variable "__main__.bad" is not valid as a type \
+                                  # N:5: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 
 [case testColumnFunctionMissingTypeAnnotation]
 # flags: --disallow-untyped-defs
diff --git a/test-data/unit/check-custom-plugin.test b/test-data/unit/check-custom-plugin.test
index d2e2221ef5e3..24b1d577a18a 100644
--- a/test-data/unit/check-custom-plugin.test
+++ b/test-data/unit/check-custom-plugin.test
@@ -497,10 +497,13 @@ Bad1 = non_declarative_base()
 Bad2 = Bad3 = declarative_base()
 
 class C1(Bad1): ...  # E: Variable "__main__.Bad1" is not valid as a type \
+                     # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases \
                      # E: Invalid base class "Bad1"
 class C2(Bad2): ...  # E: Variable "__main__.Bad2" is not valid as a type \
+                     # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases \
                      # E: Invalid base class "Bad2"
 class C3(Bad3): ...  # E: Variable "__main__.Bad3" is not valid as a type \
+                     # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases \
                      # E: Invalid base class "Bad3"
 [file mod.py]
 from typing import Generic, TypeVar
diff --git a/test-data/unit/check-errorcodes.test b/test-data/unit/check-errorcodes.test
index 89e777004551..2460c6a3f1c9 100644
--- a/test-data/unit/check-errorcodes.test
+++ b/test-data/unit/check-errorcodes.test
@@ -250,7 +250,8 @@ x: f  # E: Function "__main__.f" is not valid as a type  [valid-type] \
 
 import sys
 y: sys  # E: Module "sys" is not valid as a type  [valid-type]
-z: y  # E: Variable "__main__.y" is not valid as a type  [valid-type]
+z: y  # E: Variable "__main__.y" is not valid as a type  [valid-type] \
+      # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 
 [case testErrorCodeNeedTypeAnnotation]
 from typing import TypeVar
diff --git a/test-data/unit/check-generics.test b/test-data/unit/check-generics.test
index 63e3470c8f56..74b63a46693f 100644
--- a/test-data/unit/check-generics.test
+++ b/test-data/unit/check-generics.test
@@ -978,9 +978,11 @@ class C:
         b = int  # E: Cannot assign multiple types to name "b" without an explicit "Type[...]" annotation
     if int():
         c = int
-    def f(self, x: a) -> None: pass  # E: Variable "__main__.C.a" is not valid as a type
+    def f(self, x: a) -> None: pass  # E: Variable "__main__.C.a" is not valid as a type \
+                                     # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
     def g(self, x: b) -> None: pass
-    def h(self, x: c) -> None: pass  # E: Variable "__main__.C.c" is not valid as a type
+    def h(self, x: c) -> None: pass  # E: Variable "__main__.C.c" is not valid as a type \
+                                     # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
     x: b
     reveal_type(x)  # N: Revealed type is 'Union[builtins.int, builtins.str]'
 [out]
diff --git a/test-data/unit/check-literal.test b/test-data/unit/check-literal.test
index 96a08f344c45..44456d3460a9 100644
--- a/test-data/unit/check-literal.test
+++ b/test-data/unit/check-literal.test
@@ -697,6 +697,7 @@ y: Foo[Foo]     # E: Literal[...] must have at least one parameter
 
 NotAType = 3
 def f() -> NotAType['also' + 'not' + 'a' + 'type']: ... # E: Variable "__main__.NotAType" is not valid as a type \
+                                                        # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases \
                                                         # E: Invalid type comment or annotation
 
 # Note: this makes us re-inspect the type (e.g. via '_patch_indirect_dependencies'
@@ -891,10 +892,12 @@ d2t = 3j
 
 a2: a2t
 reveal_type(a2)      # N: Revealed type is 'Any'
-b2: b2t              # E: Variable "__main__.b2t" is not valid as a type
+b2: b2t              # E: Variable "__main__.b2t" is not valid as a type \
+                     # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 c2: c2t
 reveal_type(c2)      # N: Revealed type is 'Any'
-d2: d2t              # E: Variable "__main__.d2t" is not valid as a type
+d2: d2t              # E: Variable "__main__.d2t" is not valid as a type \
+                     # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 [builtins fixtures/complex_tuple.pyi]
 [out]
 
@@ -930,8 +933,10 @@ c: [1, 2, 3]                    # E: Bracketed expression "[...]" is not valid a
 from typing_extensions import Literal
 at = Literal[{"a": 1, "b": 2}]  # E: Invalid type alias: expression is not a valid type
 bt = {"a": 1, "b": 2}
-a: at                           # E: Variable "__main__.at" is not valid as a type
-b: bt                           # E: Variable "__main__.bt" is not valid as a type
+a: at                           # E: Variable "__main__.at" is not valid as a type \
+                                # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+b: bt                           # E: Variable "__main__.bt" is not valid as a type \
+                                # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 [builtins fixtures/dict.pyi]
 [out]
 
@@ -940,8 +945,10 @@ b: bt                           # E: Variable "__main__.bt" is not valid as a ty
 from typing_extensions import Literal
 at = Literal[{1, 2, 3}]         # E: Invalid type alias: expression is not a valid type
 bt = {1, 2, 3}
-a: at                           # E: Variable "__main__.at" is not valid as a type
-b: bt                           # E: Variable "__main__.bt" is not valid as a type
+a: at                           # E: Variable "__main__.at" is not valid as a type \
+                                # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+b: bt                           # E: Variable "__main__.bt" is not valid as a type \
+                                # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 [builtins fixtures/set.pyi]
 [out]
 
@@ -2820,13 +2827,17 @@ d: Literal[3]
 # "3" wherever it's used and get the same behavior -- so maybe we do need to support
 # at least case "b" for consistency?
 a_wrap: Literal[4, a]  # E: Parameter 2 of Literal[...] is invalid \
-                       # E: Variable "__main__.a" is not valid as a type
+                       # E: Variable "__main__.a" is not valid as a type \
+                       # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 b_wrap: Literal[4, b]  # E: Parameter 2 of Literal[...] is invalid \
-                       # E: Variable "__main__.b" is not valid as a type
+                       # E: Variable "__main__.b" is not valid as a type \
+                       # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 c_wrap: Literal[4, c]  # E: Parameter 2 of Literal[...] is invalid \
-                       # E: Variable "__main__.c" is not valid as a type
+                       # E: Variable "__main__.c" is not valid as a type \
+                       # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 d_wrap: Literal[4, d]  # E: Parameter 2 of Literal[...] is invalid \
-                       # E: Variable "__main__.d" is not valid as a type
+                       # E: Variable "__main__.d" is not valid as a type \
+                       # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 [out]
 
 [case testLiteralWithFinalPropagation]
diff --git a/test-data/unit/check-redefine.test b/test-data/unit/check-redefine.test
index 8e6368ab16be..9721df4b0284 100644
--- a/test-data/unit/check-redefine.test
+++ b/test-data/unit/check-redefine.test
@@ -276,7 +276,8 @@ def f() -> None:
     # NOTE: '"int" not callable' is due to test stubs
     y = TypeVar('y')  # E: Cannot redefine 'y' as a type variable \
                       # E: "int" not callable
-    def h(a: y) -> y: return a # E: Variable "y" is not valid as a type
+    def h(a: y) -> y: return a # E: Variable "y" is not valid as a type \
+                               # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 
 [case testCannotRedefineVarAsModule]
 # flags: --allow-redefinition
diff --git a/test-data/unit/check-semanal-error.test b/test-data/unit/check-semanal-error.test
index 87cc0aed4cce..f85dad76dd56 100644
--- a/test-data/unit/check-semanal-error.test
+++ b/test-data/unit/check-semanal-error.test
@@ -57,6 +57,7 @@ A().foo(1)
 A().x = '' # E
 [out]
 main:3: error: Variable "__main__.X" is not valid as a type
+main:3: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 main:3: error: Invalid base class "X"
 main:6: error: Incompatible types in assignment (expression has type "str", variable has type "int")
 
diff --git a/test-data/unit/check-type-aliases.test b/test-data/unit/check-type-aliases.test
index 1c0803511be5..8adfe702ba36 100644
--- a/test-data/unit/check-type-aliases.test
+++ b/test-data/unit/check-type-aliases.test
@@ -96,8 +96,10 @@ T = TypeVar('T')
 A: Type[float] = int
 if int():
     A = float  # OK
-x: A  # E: Variable "__main__.A" is not valid as a type
-def bad(tp: A) -> None:  # E: Variable "__main__.A" is not valid as a type
+x: A  # E: Variable "__main__.A" is not valid as a type \
+      # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+def bad(tp: A) -> None:  # E: Variable "__main__.A" is not valid as a type \
+                         # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
     pass
 
 Alias = int
diff --git a/test-data/unit/fine-grained.test b/test-data/unit/fine-grained.test
index fb77f534b075..d1f68bece920 100644
--- a/test-data/unit/fine-grained.test
+++ b/test-data/unit/fine-grained.test
@@ -7939,14 +7939,18 @@ x = 1
 a.py:1: error: Name 'TypeVar' is not defined
 a.py:1: note: Did you forget to import it from "typing"? (Suggestion: "from typing import TypeVar")
 a.py:7: error: Variable "a.T" is not valid as a type
+a.py:7: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 a.py:10: error: Name 'bar' already defined on line 6
 a.py:11: error: Variable "a.T" is not valid as a type
+a.py:11: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 ==
 a.py:1: error: Name 'TypeVar' is not defined
 a.py:1: note: Did you forget to import it from "typing"? (Suggestion: "from typing import TypeVar")
 a.py:7: error: Variable "a.T" is not valid as a type
+a.py:7: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 a.py:10: error: Name 'bar' already defined on line 6
 a.py:11: error: Variable "a.T" is not valid as a type
+a.py:11: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 
 [case testRefreshForWithTypeComment1]
 [file a.py]
@@ -8409,6 +8413,7 @@ B = func
 [out]
 ==
 main:5: error: Variable "b.B" is not valid as a type
+main:5: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 
 [case testNamedTupleForwardFunctionIndirect]
 # flags: --ignore-missing-imports
@@ -8425,6 +8430,7 @@ B = func
 [out]
 ==
 main:5: error: Variable "a.A" is not valid as a type
+main:5: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 
 [case testNamedTupleForwardFunctionIndirectReveal]
 # flags: --ignore-missing-imports
@@ -8451,8 +8457,10 @@ B = func
 [out]
 ==
 m.py:4: error: Variable "a.A" is not valid as a type
+m.py:4: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 ==
 m.py:4: error: Variable "a.A" is not valid as a type
+m.py:4: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 m.py:5: note: Revealed type is 'A?'
 m.py:7: note: Revealed type is 'A?'
 
@@ -8468,6 +8476,7 @@ B = int()
 [out]
 ==
 main:5: error: Variable "b.B" is not valid as a type
+main:5: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 
 [case testAliasForwardFunctionIndirect]
 # flags: --ignore-missing-imports
@@ -8484,6 +8493,7 @@ B = func
 [out]
 ==
 main:5: error: Variable "a.A" is not valid as a type
+main:5: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 
 [case testLiteralFineGrainedVarConversion]
 import mod
diff --git a/test-data/unit/merge.test b/test-data/unit/merge.test
index df621cccbe81..2a701747dd32 100644
--- a/test-data/unit/merge.test
+++ b/test-data/unit/merge.test
@@ -778,6 +778,7 @@ foo: int
 x: foo[A]
 [out]
 tmp/target.py:4: error: Variable "target.foo" is not valid as a type
+tmp/target.py:4: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 ## target
 NameExpr:3: builtins.int<0>
 NameExpr:4: foo?[target.A<1>]
diff --git a/test-data/unit/pythoneval-asyncio.test b/test-data/unit/pythoneval-asyncio.test
index cd95c6d66f94..e7f9e73f0809 100644
--- a/test-data/unit/pythoneval-asyncio.test
+++ b/test-data/unit/pythoneval-asyncio.test
@@ -502,3 +502,4 @@ def bad(arg: P) -> T:
 [out]
 _program.py:8: note: Revealed type is 'def [T] (arg: P?) -> T`-1'
 _program.py:12: error: Variable "_testForwardRefToBadAsyncShouldNotCrash_newsemanal.P" is not valid as a type
+_program.py:12: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
diff --git a/test-data/unit/semanal-errors.test b/test-data/unit/semanal-errors.test
index 042b39658df0..358d73c74181 100644
--- a/test-data/unit/semanal-errors.test
+++ b/test-data/unit/semanal-errors.test
@@ -136,6 +136,7 @@ z = 0 # type: x
 main:5: error: Function "__main__.f" is not valid as a type
 main:5: note: Perhaps you need "Callable[...]" or a callback protocol?
 main:6: error: Variable "__main__.x" is not valid as a type
+main:6: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 
 [case testGlobalVarRedefinition]
 import typing
@@ -801,7 +802,8 @@ cast([int, str], None)   # E: Bracketed expression "[...]" is not valid as a typ
 
 from typing import cast
 x = 0
-cast(x, None)        # E: Variable "__main__.x" is not valid as a type
+cast(x, None)        # E: Variable "__main__.x" is not valid as a type \
+                     # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 cast(t, None)        # E: Name 't' is not defined
 cast(__builtins__.x, None) # E: Name '__builtins__.x' is not defined
 [out]
@@ -896,7 +898,8 @@ main:4: error: Type cannot be declared in assignment to non-self attribute
 from typing import TypeVar, Generic
 t = TypeVar('t')
 class A(Generic[t]): pass
-A[TypeVar] # E: Variable "typing.TypeVar" is not valid as a type
+A[TypeVar] # E: Variable "typing.TypeVar" is not valid as a type \
+           # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 [out]
 
 [case testInvalidTypeInTypeApplication2]
diff --git a/test-data/unit/semanal-typealiases.test b/test-data/unit/semanal-typealiases.test
index c72cb9d08842..045ef201b13f 100644
--- a/test-data/unit/semanal-typealiases.test
+++ b/test-data/unit/semanal-typealiases.test
@@ -403,13 +403,15 @@ MypyFile:1(
 
 import typing
 A = [int, str]
-a = 1 # type: A  # E: Variable "__main__.A" is not valid as a type
+a = 1 # type: A  # E: Variable "__main__.A" is not valid as a type \
+                 # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 
 [case testCantUseStringLiteralAsTypeAlias]
 
 from typing import Union
 A = 'Union[int, str]'
-a = 1 # type: A  # E: Variable "__main__.A" is not valid as a type
+a = 1 # type: A  # E: Variable "__main__.A" is not valid as a type \
+                 # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 
 [case testStringLiteralTypeAsAliasComponent]
 from typing import Union

From 05d2845fa4b249b0db89746bec55558a26b82b75 Mon Sep 17 00:00:00 2001
From: Xuanda Yang <th3charlie@gmail.com>
Date: Tue, 28 Jan 2020 00:45:25 +0800
Subject: [PATCH 4/5] fix py3.8

---
 test-data/unit/check-python38.test | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/test-data/unit/check-python38.test b/test-data/unit/check-python38.test
index f0a346a40c4c..1a3e2407b0fe 100644
--- a/test-data/unit/check-python38.test
+++ b/test-data/unit/check-python38.test
@@ -238,10 +238,12 @@ def f(x: int = (c := 4)) -> int:
 
     # Just make sure we don't crash on this sort of thing.
     if NT := NamedTuple("NT", [("x", int)]):  # E: "int" not callable
-        z2: NT  # E: Variable "NT" is not valid as a type
+        z2: NT  # E: Variable "NT" is not valid as a type \
+                # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 
     if Alias := int:
-        z3: Alias  # E: Variable "Alias" is not valid as a type
+        z3: Alias  # E: Variable "Alias" is not valid as a type \
+                   # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
 
     if (reveal_type(y9 := 3) and   # N: Revealed type is 'Literal[3]?'
             reveal_type(y9)):       # N: Revealed type is 'builtins.int'

From a91f4145d94d231ba2a28ad1ca1dc3ca40b5d6f2 Mon Sep 17 00:00:00 2001
From: Xuanda Yang <th3charlie@gmail.com>
Date: Thu, 30 Jan 2020 08:49:46 +0800
Subject: [PATCH 5/5] change title

---
 docs/source/common_issues.rst           |  2 +-
 mypy/typeanal.py                        |  2 +-
 test-data/unit/check-columns.test       | 18 +++++++++---------
 test-data/unit/check-custom-plugin.test |  6 +++---
 test-data/unit/check-errorcodes.test    |  2 +-
 test-data/unit/check-generics.test      |  4 ++--
 test-data/unit/check-literal.test       | 22 +++++++++++-----------
 test-data/unit/check-python38.test      |  4 ++--
 test-data/unit/check-redefine.test      |  2 +-
 test-data/unit/check-semanal-error.test |  2 +-
 test-data/unit/check-type-aliases.test  |  4 ++--
 test-data/unit/fine-grained.test        | 20 ++++++++++----------
 test-data/unit/merge.test               |  2 +-
 test-data/unit/pythoneval-asyncio.test  |  2 +-
 test-data/unit/semanal-errors.test      |  6 +++---
 test-data/unit/semanal-typealiases.test |  4 ++--
 16 files changed, 51 insertions(+), 51 deletions(-)

diff --git a/docs/source/common_issues.rst b/docs/source/common_issues.rst
index c06f035d4979..6891b3262547 100644
--- a/docs/source/common_issues.rst
+++ b/docs/source/common_issues.rst
@@ -711,7 +711,7 @@ You can install the latest development version of mypy from source. Clone the
     cd mypy
     sudo python3 -m pip install --upgrade .
 
-Differentiate variables and aliases
+Variables vs type aliases
 -----------------------------------
 
 Mypy has both type aliases and variables with types like ``Type[...]`` and it is important to know their difference.
diff --git a/mypy/typeanal.py b/mypy/typeanal.py
index 4f197324b610..ed5d0e0474e4 100644
--- a/mypy/typeanal.py
+++ b/mypy/typeanal.py
@@ -424,7 +424,7 @@ def analyze_unbound_type_without_type_info(self, t: UnboundType, sym: SymbolTabl
         notes = []  # type: List[str]
         if isinstance(sym.node, Var):
             notes.append('See https://mypy.readthedocs.io/en/'
-                         'latest/common_issues.html#differentiate-variables-and-aliases')
+                         'latest/common_issues.html#variables-vs-type-aliases')
             message = 'Variable "{}" is not valid as a type'
         elif isinstance(sym.node, (SYMBOL_FUNCBASE_TYPES, Decorator)):
             message = 'Function "{}" is not valid as a type'
diff --git a/test-data/unit/check-columns.test b/test-data/unit/check-columns.test
index fecf17d27482..206ff15a9d91 100644
--- a/test-data/unit/check-columns.test
+++ b/test-data/unit/check-columns.test
@@ -154,21 +154,21 @@ from typing import Iterable
 bad = 0
 
 def f(x: bad): # E:10: Variable "__main__.bad" is not valid as a type \
-               # N:10: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+               # N:10: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
     y: bad # E:8: Variable "__main__.bad" is not valid as a type \
-           # N:8: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+           # N:8: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 
 if int():
     def g(x): # E:5: Variable "__main__.bad" is not valid as a type \
-              # N:5: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+              # N:5: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
         # type: (bad) -> None
         y = 0  # type: bad  # E:9: Variable "__main__.bad" is not valid as a type \
-                            # N:9: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+                            # N:9: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 
 z: Iterable[bad] # E:13: Variable "__main__.bad" is not valid as a type \
-                 # N:13: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+                 # N:13: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 h: bad[int] # E:4: Variable "__main__.bad" is not valid as a type \
-            # N:4: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+            # N:4: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 
 [case testColumnInvalidType_python2]
 
@@ -178,13 +178,13 @@ bad = 0
 
 if int():
     def g(x): # E:5: Variable "__main__.bad" is not valid as a type \
-              # N:5: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+              # N:5: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
         # type: (bad) -> None
         y = 0  # type: bad  # E:9: Variable "__main__.bad" is not valid as a type \
-                            # N:9: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+                            # N:9: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 
     z = ()  # type: Iterable[bad] # E:5: Variable "__main__.bad" is not valid as a type \
-                                  # N:5: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+                                  # N:5: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 
 [case testColumnFunctionMissingTypeAnnotation]
 # flags: --disallow-untyped-defs
diff --git a/test-data/unit/check-custom-plugin.test b/test-data/unit/check-custom-plugin.test
index 0b40f9f7f884..77225b7df9ba 100644
--- a/test-data/unit/check-custom-plugin.test
+++ b/test-data/unit/check-custom-plugin.test
@@ -498,13 +498,13 @@ Bad1 = non_declarative_base()
 Bad2 = Bad3 = declarative_base()
 
 class C1(Bad1): ...  # E: Variable "__main__.Bad1" is not valid as a type \
-                     # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases \
+                     # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases \
                      # E: Invalid base class "Bad1"
 class C2(Bad2): ...  # E: Variable "__main__.Bad2" is not valid as a type \
-                     # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases \
+                     # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases \
                      # E: Invalid base class "Bad2"
 class C3(Bad3): ...  # E: Variable "__main__.Bad3" is not valid as a type \
-                     # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases \
+                     # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases \
                      # E: Invalid base class "Bad3"
 [file mod.py]
 from typing import Generic, TypeVar
diff --git a/test-data/unit/check-errorcodes.test b/test-data/unit/check-errorcodes.test
index 109f154187c6..c0e3a9782b5e 100644
--- a/test-data/unit/check-errorcodes.test
+++ b/test-data/unit/check-errorcodes.test
@@ -251,7 +251,7 @@ x: f  # E: Function "__main__.f" is not valid as a type  [valid-type] \
 import sys
 y: sys  # E: Module "sys" is not valid as a type  [valid-type]
 z: y  # E: Variable "__main__.y" is not valid as a type  [valid-type] \
-      # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+      # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 [builtins fixtures/tuple.pyi]
 
 [case testErrorCodeNeedTypeAnnotation]
diff --git a/test-data/unit/check-generics.test b/test-data/unit/check-generics.test
index 4f65e9df6700..9b1af9a47628 100644
--- a/test-data/unit/check-generics.test
+++ b/test-data/unit/check-generics.test
@@ -986,10 +986,10 @@ class C:
     if int():
         c = int
     def f(self, x: a) -> None: pass  # E: Variable "__main__.C.a" is not valid as a type \
-                                     # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+                                     # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
     def g(self, x: b) -> None: pass
     def h(self, x: c) -> None: pass  # E: Variable "__main__.C.c" is not valid as a type \
-                                     # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+                                     # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
     x: b
     reveal_type(x)  # N: Revealed type is 'Union[builtins.int, builtins.str]'
 [out]
diff --git a/test-data/unit/check-literal.test b/test-data/unit/check-literal.test
index 7fba7d330acc..1d401986e8e6 100644
--- a/test-data/unit/check-literal.test
+++ b/test-data/unit/check-literal.test
@@ -707,7 +707,7 @@ y: Foo[Foo]     # E: Literal[...] must have at least one parameter
 
 NotAType = 3
 def f() -> NotAType['also' + 'not' + 'a' + 'type']: ... # E: Variable "__main__.NotAType" is not valid as a type \
-                                                        # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases \
+                                                        # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases \
                                                         # E: Invalid type comment or annotation
 
 # Note: this makes us re-inspect the type (e.g. via '_patch_indirect_dependencies'
@@ -909,11 +909,11 @@ d2t = 3j
 a2: a2t
 reveal_type(a2)      # N: Revealed type is 'Any'
 b2: b2t              # E: Variable "__main__.b2t" is not valid as a type \
-                     # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+                     # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 c2: c2t
 reveal_type(c2)      # N: Revealed type is 'Any'
 d2: d2t              # E: Variable "__main__.d2t" is not valid as a type \
-                     # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+                     # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 [builtins fixtures/complex_tuple.pyi]
 [out]
 
@@ -953,9 +953,9 @@ from typing_extensions import Literal
 at = Literal[{"a": 1, "b": 2}]  # E: Invalid type alias: expression is not a valid type
 bt = {"a": 1, "b": 2}
 a: at                           # E: Variable "__main__.at" is not valid as a type \
-                                # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+                                # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 b: bt                           # E: Variable "__main__.bt" is not valid as a type \
-                                # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+                                # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 [builtins fixtures/dict.pyi]
 [out]
 
@@ -965,9 +965,9 @@ from typing_extensions import Literal
 at = Literal[{1, 2, 3}]         # E: Invalid type alias: expression is not a valid type
 bt = {1, 2, 3}
 a: at                           # E: Variable "__main__.at" is not valid as a type \
-                                # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+                                # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 b: bt                           # E: Variable "__main__.bt" is not valid as a type \
-                                # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+                                # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 [builtins fixtures/set.pyi]
 [out]
 
@@ -2876,16 +2876,16 @@ d: Literal[3]
 # at least case "b" for consistency?
 a_wrap: Literal[4, a]  # E: Parameter 2 of Literal[...] is invalid \
                        # E: Variable "__main__.a" is not valid as a type \
-                       # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+                       # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 b_wrap: Literal[4, b]  # E: Parameter 2 of Literal[...] is invalid \
                        # E: Variable "__main__.b" is not valid as a type \
-                       # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+                       # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 c_wrap: Literal[4, c]  # E: Parameter 2 of Literal[...] is invalid \
                        # E: Variable "__main__.c" is not valid as a type \
-                       # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+                       # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 d_wrap: Literal[4, d]  # E: Parameter 2 of Literal[...] is invalid \
                        # E: Variable "__main__.d" is not valid as a type \
-                       # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+                       # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 [builtins fixtures/tuple.pyi]
 [out]
 
diff --git a/test-data/unit/check-python38.test b/test-data/unit/check-python38.test
index 1a3e2407b0fe..98eda306c731 100644
--- a/test-data/unit/check-python38.test
+++ b/test-data/unit/check-python38.test
@@ -239,11 +239,11 @@ def f(x: int = (c := 4)) -> int:
     # Just make sure we don't crash on this sort of thing.
     if NT := NamedTuple("NT", [("x", int)]):  # E: "int" not callable
         z2: NT  # E: Variable "NT" is not valid as a type \
-                # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+                # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 
     if Alias := int:
         z3: Alias  # E: Variable "Alias" is not valid as a type \
-                   # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+                   # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 
     if (reveal_type(y9 := 3) and   # N: Revealed type is 'Literal[3]?'
             reveal_type(y9)):       # N: Revealed type is 'builtins.int'
diff --git a/test-data/unit/check-redefine.test b/test-data/unit/check-redefine.test
index 9721df4b0284..d5f453c4e84d 100644
--- a/test-data/unit/check-redefine.test
+++ b/test-data/unit/check-redefine.test
@@ -277,7 +277,7 @@ def f() -> None:
     y = TypeVar('y')  # E: Cannot redefine 'y' as a type variable \
                       # E: "int" not callable
     def h(a: y) -> y: return a # E: Variable "y" is not valid as a type \
-                               # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+                               # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 
 [case testCannotRedefineVarAsModule]
 # flags: --allow-redefinition
diff --git a/test-data/unit/check-semanal-error.test b/test-data/unit/check-semanal-error.test
index 8be428a73a80..ac8f72b4cd36 100644
--- a/test-data/unit/check-semanal-error.test
+++ b/test-data/unit/check-semanal-error.test
@@ -57,7 +57,7 @@ A().foo(1)
 A().x = '' # E
 [out]
 main:3: error: Variable "__main__.X" is not valid as a type
-main:3: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+main:3: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 main:3: error: Invalid base class "X"
 main:6: error: Incompatible types in assignment (expression has type "str", variable has type "int")
 
diff --git a/test-data/unit/check-type-aliases.test b/test-data/unit/check-type-aliases.test
index 5197a92d3a6c..cab61d7dcffb 100644
--- a/test-data/unit/check-type-aliases.test
+++ b/test-data/unit/check-type-aliases.test
@@ -100,9 +100,9 @@ A: Type[float] = int
 if int():
     A = float  # OK
 x: A  # E: Variable "__main__.A" is not valid as a type \
-      # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+      # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 def bad(tp: A) -> None:  # E: Variable "__main__.A" is not valid as a type \
-                         # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+                         # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
     pass
 
 Alias = int
diff --git a/test-data/unit/fine-grained.test b/test-data/unit/fine-grained.test
index 5073bac5fa3e..ad8357f3d4e9 100644
--- a/test-data/unit/fine-grained.test
+++ b/test-data/unit/fine-grained.test
@@ -7951,18 +7951,18 @@ x = 1
 a.py:1: error: Name 'TypeVar' is not defined
 a.py:1: note: Did you forget to import it from "typing"? (Suggestion: "from typing import TypeVar")
 a.py:7: error: Variable "a.T" is not valid as a type
-a.py:7: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+a.py:7: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 a.py:10: error: Name 'bar' already defined on line 6
 a.py:11: error: Variable "a.T" is not valid as a type
-a.py:11: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+a.py:11: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 ==
 a.py:1: error: Name 'TypeVar' is not defined
 a.py:1: note: Did you forget to import it from "typing"? (Suggestion: "from typing import TypeVar")
 a.py:7: error: Variable "a.T" is not valid as a type
-a.py:7: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+a.py:7: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 a.py:10: error: Name 'bar' already defined on line 6
 a.py:11: error: Variable "a.T" is not valid as a type
-a.py:11: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+a.py:11: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 
 [case testRefreshForWithTypeComment1]
 [file a.py]
@@ -8427,7 +8427,7 @@ B = func
 [out]
 ==
 main:5: error: Variable "b.B" is not valid as a type
-main:5: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+main:5: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 
 [case testNamedTupleForwardFunctionIndirect]
 # flags: --ignore-missing-imports
@@ -8445,7 +8445,7 @@ B = func
 [out]
 ==
 main:5: error: Variable "a.A" is not valid as a type
-main:5: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+main:5: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 
 [case testNamedTupleForwardFunctionIndirectReveal]
 # flags: --ignore-missing-imports
@@ -8473,10 +8473,10 @@ B = func
 [out]
 ==
 m.py:4: error: Variable "a.A" is not valid as a type
-m.py:4: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+m.py:4: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 ==
 m.py:4: error: Variable "a.A" is not valid as a type
-m.py:4: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+m.py:4: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 m.py:5: note: Revealed type is 'A?'
 m.py:7: note: Revealed type is 'A?'
 
@@ -8492,7 +8492,7 @@ B = int()
 [out]
 ==
 main:5: error: Variable "b.B" is not valid as a type
-main:5: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+main:5: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 
 [case testAliasForwardFunctionIndirect]
 # flags: --ignore-missing-imports
@@ -8509,7 +8509,7 @@ B = func
 [out]
 ==
 main:5: error: Variable "a.A" is not valid as a type
-main:5: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+main:5: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 
 [case testLiteralFineGrainedVarConversion]
 import mod
diff --git a/test-data/unit/merge.test b/test-data/unit/merge.test
index 1d8c94ecf882..aafcbc2427a6 100644
--- a/test-data/unit/merge.test
+++ b/test-data/unit/merge.test
@@ -779,7 +779,7 @@ foo: int
 x: foo[A]
 [out]
 tmp/target.py:4: error: Variable "target.foo" is not valid as a type
-tmp/target.py:4: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+tmp/target.py:4: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 ## target
 NameExpr:3: builtins.int<0>
 NameExpr:4: foo?[target.A<1>]
diff --git a/test-data/unit/pythoneval-asyncio.test b/test-data/unit/pythoneval-asyncio.test
index e7f9e73f0809..48b9bd3a0bb7 100644
--- a/test-data/unit/pythoneval-asyncio.test
+++ b/test-data/unit/pythoneval-asyncio.test
@@ -502,4 +502,4 @@ def bad(arg: P) -> T:
 [out]
 _program.py:8: note: Revealed type is 'def [T] (arg: P?) -> T`-1'
 _program.py:12: error: Variable "_testForwardRefToBadAsyncShouldNotCrash_newsemanal.P" is not valid as a type
-_program.py:12: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+_program.py:12: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
diff --git a/test-data/unit/semanal-errors.test b/test-data/unit/semanal-errors.test
index 448398336722..f92a1a5e338f 100644
--- a/test-data/unit/semanal-errors.test
+++ b/test-data/unit/semanal-errors.test
@@ -137,7 +137,7 @@ z = 0 # type: x
 main:5: error: Function "__main__.f" is not valid as a type
 main:5: note: Perhaps you need "Callable[...]" or a callback protocol?
 main:6: error: Variable "__main__.x" is not valid as a type
-main:6: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+main:6: note: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 
 [case testGlobalVarRedefinition]
 import typing
@@ -804,7 +804,7 @@ cast([int, str], None)   # E: Bracketed expression "[...]" is not valid as a typ
 from typing import cast
 x = 0
 cast(x, None)        # E: Variable "__main__.x" is not valid as a type \
-                     # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+                     # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 cast(t, None)        # E: Name 't' is not defined
 cast(__builtins__.x, None) # E: Name '__builtins__.x' is not defined
 [out]
@@ -900,7 +900,7 @@ from typing import TypeVar, Generic
 t = TypeVar('t')
 class A(Generic[t]): pass
 A[TypeVar] # E: Variable "typing.TypeVar" is not valid as a type \
-           # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+           # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 [out]
 
 [case testInvalidTypeInTypeApplication2]
diff --git a/test-data/unit/semanal-typealiases.test b/test-data/unit/semanal-typealiases.test
index 715be40c7b71..46af11674717 100644
--- a/test-data/unit/semanal-typealiases.test
+++ b/test-data/unit/semanal-typealiases.test
@@ -405,14 +405,14 @@ MypyFile:1(
 import typing
 A = [int, str]
 a = 1 # type: A  # E: Variable "__main__.A" is not valid as a type \
-                 # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+                 # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 
 [case testCantUseStringLiteralAsTypeAlias]
 
 from typing import Union
 A = 'Union[int, str]'
 a = 1 # type: A  # E: Variable "__main__.A" is not valid as a type \
-                 # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#differentiate-variables-and-aliases
+                 # N: See https://mypy.readthedocs.io/en/latest/common_issues.html#variables-vs-type-aliases
 
 [case testStringLiteralTypeAsAliasComponent]
 from typing import Union