docs/changelog.rst

@@ -4,6 +4,21 @@ Release History
 
 .. towncrier release notes start
 
+v4.2.0 (2023-01-03)
+-------------------
+
+Features - 4.2.0
+~~~~~~~~~~~~~~~~
+- Packaging environments now inherit from the ``pkgenv`` section, allowing to set all your packaging options in one place,
+  and support the ``deps`` key to set additional dependencies that will be installed after ``pyprojec.toml`` static
+  ``requires`` but before backends dynamic requires - by :user:`gaborbernat`. (:issue:`2543`)
+
+Improved Documentation - 4.2.0
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+- Document breaking changes with tox 4 and packaging environments - by :user:`gaborbernat`. (:issue:`2543`)
+- Document how to handle environments whose names match ``tox`` subcommands - by :user:`sirosen`. (:issue:`2728`)
+
+
 v4.1.3 (2023-01-02)
 -------------------
 

docs/faq.rst

@@ -1,145 +1,15 @@
+.. _faq:
+
 FAQ
 ===
 
 Here you'll find answers to some frequently asked questions.
 
 Breaking changes in tox 4
 -------------------------
-Version 4 of tox should be mostly backwards compatible with version 3, with the following exceptions:
-
-tox 4 - Python support
-++++++++++++++++++++++
-- tox now requires Python ``3.7`` or later and is tested only against CPython. You can still create test environments
-  for earlier Python versions or different Python interpreters. PyPy support is best effort, meaning we do not test it
-  as part of our CI runs, however if you discover issues under PyPy we will accept PRs addressing it.
-
-tox 4 - changed INI rules
-+++++++++++++++++++++++++
-- The hash sign (``#``) now always acts as comment within ``tox.ini`` or ``setup.cfg`` tox configuration file. Where you
-  need to pass on a ``#`` character you will need to escape it in form of ``\#`` so tox does not handle everything right
-  of the ``#`` character as a comment. Valid in tox 3:
-
-  .. code-block:: ini
-
-      # valid in tox 3
-      commands = bash -c "echo 'foo#bar'"
-
-      # valid in tox 4
-      commands = bash -c "echo 'foo\#bar'"
-
-- Within the ``pass_env`` you can no longer use space as value separator, instead you need to use the ``,`` or the
-  newline character. This is to have the same value separation rules for all tox configuration lines.
-
-  .. code-block:: ini
-
-      # valid in tox 3
-      passenv = ALPHA BETA
-      passenv =
-          ALPHA
-          BETA
-
-      # valid in tox 4
-      passenv = ALPHA, BETA
-      passenv =
-          ALPHA
-          BETA
-
-- tox 4 now errors when using the ``-U`` flag when defining dependencies, e.g. ``deps = -Ur requirements.txt``. While
-  this worked in tox 3, it was never supported officially. Additionally, in the context of a new virtual environment
-  this flag makes no sense anyway.
-
-- tox 4 requires the ``install_command`` to evaluate to a non-empty value for each target environment.  In tox 3, an
-  empty value would be substituted for the default install command.
-
-tox 4 - known regressions
-+++++++++++++++++++++++++
-
-- With tox 4 the tty trait of the caller environment is no longer passed through. The most notable impact of this is
-  that some tools no longer print colored output. A PR to address this is welcomed, in the meantime you can use the
-  ``tty`` substitution to force color mode for these tools, see for example tox itself with pytest and mypy
-  `here in tox.ini <https://github.com/tox-dev/tox/blob/main/tox.ini#L28>`_.
-
-tox 4 - new plugin system
-+++++++++++++++++++++++++
-
-tox 4 is a grounds up rewrite of the code base, and while we kept the configuration layer compatibility no such effort
-has been made for the programmatic API. Therefore, all plugins will need to redo their integration against the new code
-base. If you're a plugin developer refer to the `plugin documentation <https://tox.wiki/en/latest/plugins.html>`_ for
-more information.
-
-tox 4 - removed tox.ini keys
-++++++++++++++++++++++++++++
-
-+--------------------------+----------------------------------------------+
-| Configuration key        | Migration path                               |
-+==========================+==============================================+
-| ``indexserver``          | See `Using a custom PyPI server`_.           |
-+--------------------------+----------------------------------------------+
-| ``whitelist_externals``  | Use :ref:`allowlist_externals` key instead.  |
-+--------------------------+----------------------------------------------+
-| ``isolated_build``       | Isolated builds are now always used.         |
-+--------------------------+----------------------------------------------+
-| ``distdir``              | Use the ``TOX_PACKAGE`` environment variable.|
-+--------------------------+----------------------------------------------+
-
-tox 4 - basepython not resolved
-+++++++++++++++++++++++++++++++
-The base python configuration is no longer resolved to ``pythonx.y`` format, instead is kept as ``py39``, and is
-the virtualenv project that handles mapping that to a Python interpreter. If you were using this variable we recommend
-moving to the newly added ``py_impl`` and ``py_dot_ver`` variables, for example:
-
-.. code-block:: ini
-
-   deps = -r{py_impl}{py_dot_ver}-req.txt
-
-tox 4 - substitutions removed
-+++++++++++++++++++++++++++++
-- The ``distshare`` substitution has been removed.
-
-tox 4 - disallowed env names
-++++++++++++++++++++++++++++
-- Environment names that contain multiple Python variants, such as ``name-py39-pypy`` or ``py39-py310`` will now raise
-  an error, previously this only warned, you can use :ref:`ignore_basepython_conflict` to disable this error, but we
-  recommend changing the name to avoid this name that can be confusing.
-
-tox 4 - CLI arguments changed
-+++++++++++++++++++++++++++++
-- The ``--parallel--safe-build`` CLI argument has been removed, no longer needed.
-- When you want to pass an option to a test command, e.g. to ``pytest``, now you must use ``--`` as a separator, this
-  worked with version 3 also, but any unknown trailing arguments were automatically passed through, while now this is
-  no longer the case.
-- Running ``--showconfig`` or ``--help-ini`` with the ``-v`` flag will add interleaved debugging information, whereas
-  tox 3 added additional lines at the start. If you want to generate valid ini files you must not use the ``-v`` flag.
-- The ``--index-url`` is now removed, use ``PIP_INDEX_URL`` in :ref:`set_env` instead.
-
-tox 4 - packaging changes
-+++++++++++++++++++++++++
-- We use isolated builds (always) as specified by :pep:`518` and use :pep:`517` to communicate with the build backend.
-- The ``--develop`` CLI flag or the :ref:`use_develop` settings now enables editable installations via the :pep:`660`
-  mechanism rather than the legacy ``pip install -e`` behaviour. The old functionality can still be forced by setting
-  the :ref:`package` setting for the run environment to ``editable-legacy``.
-
-tox 4 -- output changes
-+++++++++++++++++++++++
-- We now use colors for reporting, to help make the output easier to read for humans. This can be disabled via the
-  ``TERM=dumb`` or ``NO_COLOR=1`` environment variables, or the ``--colored no`` CLI argument.
-
-tox 4 -- re-use of environments
-+++++++++++++++++++++++++++++++
-
-- It is no longer possible to re-use environments. While this might have been possible with tox version 3, this
-  behavior was never supported, and possibly caused wrong results as illustrated in the following example.
-
-.. code-block:: ini
-
-    [testenv]
-    envdir = .tox/venv
 
-    [testenv:a]
-    deps = pytest>7
-
-    [testenv:b]
-    deps = pytest<7
+Version 4 of tox should be mostly backwards compatible with version 3.
+Exceptions and guidance for migrating are given in the :ref:`upgrading doc <upgrading>`.
 
 New features in tox 4
 ---------------------
@@ -195,6 +65,8 @@ Here is a non-exhaustive list of these.
   label by using the ``-m label`` CLI flag (instead of the ``-e list_of_envs``).
 - You can now invoke all tox environments within a given factor via the ``-f factor`` CLI flag.
 
+.. _faq_custom_pypi_server:
+
 Using a custom PyPI server
 --------------------------
 By default tox uses pip to install Python dependencies. Therefore to change the index server you should configure pip

docs/index.rst

@@ -76,3 +76,4 @@ you want to do more research, we recommend taking a look at these projects:
    plugins_api
    development
    changelog
+   upgrading