Document ambiguous usages in v3-to-v4 (#2808)

* Document ambiguous usages in v3-to-v4

Add a section to the upgrading doc,
"Legacy CLI entry point may result in ambiguous usages"

The new section resolves #2728

* Updates per review: CLI compat doc section

Retitle the section. Split it into two subsections, one on ``-e`` vs
``run -e``, and one on command names matching environments (as a
specific case).

Author: sirosen

docs/changelog/2728.doc.rst

@@ -0,0 +1 @@
+Document how to handle environments whose names match ``tox`` subcommands - by :user:`sirosen`.

docs/upgrading.rst

@@ -149,3 +149,76 @@ Re-use of environments
 
     [testenv:b]
     deps = pytest<7
+
+
+CLI command compatibility
+-------------------------
+
+``tox`` 4 introduced dedicated subcommands for various usages.
+However, when no subcommand is given the legacy entry point which imitates ``tox`` 3 is used.
+
+This compatibility feature makes most ``tox`` 3 commands work in ``tox`` 4, but there are some exceptions.
+
+Updating usage with ``-e``
+++++++++++++++++++++++++++
+
+In ``tox`` 3, environments could be specified to run with the ``-e`` flag.
+In ``tox`` 4, environments should always be specified using the ``-e`` flag to the ``run`` subcommand.
+
+Rewrite usages as follows
+
+.. code:: bash
+
+    # tox 3
+    tox -e py310,style
+
+    # tox 4
+    tox run -e py310,style
+
+    # or, tox 4 with the short alias
+    tox r -e py310,style
+
+Environment names matching commands
++++++++++++++++++++++++++++++++++++
+
+Now that ``tox`` has subcommands, it is possible for arguments to ``tox`` or its options to match those subcommand
+names.
+When that happens, parsing can become ambiguous between the ``tox`` 4 usage and the legacy fallback behavior.
+
+For example, consider the following tox config:
+
+.. code-block:: ini
+
+    [tox]
+    env_list = py39,py310
+
+    [testenv]
+    commands =
+        python -c 'print("hi")'
+
+    [testenv:list]
+    commands =
+        python -c 'print("a, b, c")'
+
+This defines an environment whose name matches a ``tox`` 4 command, ``list``.
+
+Under ``tox`` 3, ``tox -e list`` specified the ``list`` environment.
+However, under ``tox`` 4, the parse of this usage as an invocation of ``tox list`` takes precedence over the legacy
+behavior.
+
+Therefore, attempting that same usage results in an error:
+
+.. code:: bash
+
+    $ tox -e list
+    ...
+    tox: error: unrecognized arguments: -e
+
+This is best avoided by updating to non-legacy usage:
+
+.. code:: bash
+
+    $ tox run -e list
+
+    # or, equivalently...
+    $ tox r -e list