tox: Soft-deprecate '[tox] min_version'

We don't raise a warning or similar: this is purely to encourage new
users (and existing users reworking their tox.ini files) to prefer
'[tox] requires'.

Signed-off-by: Stephen Finucane <[email protected]>

Author: stephenfin

docs/changelog/3553.doc.rst

@@ -0,0 +1 @@
+The ``min_version``/``minversion`` config option is deprecated in favor of the ``requires`` option.

docs/config.rst

@@ -46,7 +46,8 @@ For example:
 .. code-block:: ini
 
     [tox]
-    min_version = 4.20
+    requires =
+        tox >= 4.20
     env_list =
         3.13
         3.12
@@ -74,7 +75,8 @@ This configuration file uses:
 .. code-block:: ini
 
     [tox:tox]
-    min_version = 4.0
+    requires =
+        tox >= 4.20
     env_list =
         3.13
         3.12
@@ -98,7 +100,8 @@ instead inside the ``pyproject.toml`` file under the ``tool.tox`` table and ``le
     [tool.tox]
     legacy_tox_ini = """
         [tox]
-        min_version = 4.0
+        requires =
+            tox >= 4.20
         env_list =
             py310
             py39
@@ -203,6 +206,9 @@ The following options are set in the ``[tox]`` section of ``tox.ini`` or the ``[
 .. conf::
    :keys: min_version, minversion
    :default: <current version of tox>
+   :version_deprecated: 4.28.0
+
+   **DEPRECATED** Prefer requiring a minimum tox version via :ref:`requires`.
 
    A string to define the minimal tox version required to run. If the host's tox version is less than this, it will
    automatically create a provisioned tox environment that satisfies this requirement. See :ref:`provision_tox_env`

docs/upgrading.rst

@@ -321,6 +321,6 @@ version is above the version this feature was added to it, for example for setup
 Provisioning environment
 ------------------------
 
-The provisioning environment is triggered when ``minversion`` or ``requires`` are specified and the current environment
+The provisioning environment is triggered when ``min_version`` or ``requires`` are specified and the current environment
 does not satisfy the requirement. In tox 4, the provisioning environment (``.tox`` by default) must be explicitly
 configured and will not inherit values from ``[testenv]`` section.

docs/user_guide.rst

@@ -385,7 +385,8 @@ you want to do more research, we recommend taking a look at these projects:
 
 Auto-provisioning
 -----------------
-In case the installed tox version does not satisfy either the :ref:`min_version` or the :ref:`requires`, tox will automatically
+
+In case the installed tox version does not satisfy either the :ref:`requires` or the :ref:`min_version`, tox will automatically
 create a virtual environment under :ref:`provision_tox_env` name that satisfies those constraints and delegate all
 calls to this meta environment. This should allow satisfying constraints on your tox environment automatically,
 given you have at least version ``3.8.0`` of tox.
@@ -396,17 +397,16 @@ For example given:
 
    .. code-block:: toml
 
-        min_version = "4"
-        requires = ["tox-uv>=1"]
+        requires = ["tox>=4", "tox-uv>=1"]
 
 .. tab:: INI
 
    .. code-block:: ini
 
         [tox]
-        min_version = 4
-        requires = tox-uv>=1
-
+        requires =
+            tox>=4
+            tox-uv>=1
 
 if the user runs it with tox ``3.8`` or later the installed tox application will automatically ensure that both the minimum version and
 requires constraints are satisfied, by creating a virtual environment under ``.tox`` folder, and then installing into it