Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Introduce Upgrading doc page for tox4
This adds a new page to the docs, Upgrading, meant to remove the documentation regarding backwards incompatible changes in tox4 from the FAQ into a dedicated page. The content of the page is primarily a lift-and-shift of the breaking changes section of the FAQ, and the FAQ page and Upgrading pages now cross-link to one another. New content is added to the Upgrading page in the form of - a preamble for the doc - a section, "Legacy CLI entry point may result in ambiguous usages" The new section resolves #2728
- Loading branch information
Showing
3 changed files
with
193 additions
and
131 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,186 @@ | ||
| .. _upgrading: | ||
|
|
||
| Upgrading to tox v4 | ||
| =================== | ||
|
|
||
| Version 4 is mostly backwards compatible. | ||
| This document covers all breaking changes and, where applicable, includes guidance on how to update. | ||
|
|
||
| See also the list of new features in the :ref:`FAQ <faq>`. | ||
|
|
||
| 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. | ||
|
|
||
| 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. | ||
|
|
||
| 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>`_. | ||
|
|
||
| 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. | ||
|
|
||
| Removed tox.ini keys | ||
| -------------------- | ||
|
|
||
| +--------------------------+-----------------------------------------------------------------+ | ||
| | Configuration key | Migration path | | ||
| +==========================+=================================================================+ | ||
| | ``indexserver`` | See :ref:`Using a custom PyPI server <faq_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. | | ||
| +--------------------------+-----------------------------------------------------------------+ | ||
|
|
||
| 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 | ||
| Substitutions removed | ||
| --------------------- | ||
| - The ``distshare`` substitution has been removed. | ||
|
|
||
| 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. | ||
|
|
||
| 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. | ||
|
|
||
| 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``. | ||
|
|
||
| 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. | ||
|
|
||
| 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 | ||
| Legacy CLI entry point may result in ambiguous usages | ||
| ----------------------------------------------------- | ||
|
|
||
| ``tox`` 4 introduced dedicated subcommands for various usages. | ||
| For example, ``tox run -e foo`` replaces ``tox -e foo``. | ||
| However, when no recognized command is given the legacy entry point which imitates ``tox`` 3 is used. | ||
|
|
||
| As a result, commands which were previously unambiguous may have become ambiguous. | ||
|
|
||
| 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. | ||
|
|
||
| Under ``tox`` 4, this usage parses as an invocation of ``tox list``. | ||
| Therefore, attempting that same usage results in an error: | ||
|
|
||
| .. code:: bash | ||
| $ tox -e list | ||
| ... | ||
| tox: error: unrecognized arguments: -e | ||
| It can be run either with an explicit ``tox run`` or an explicit use of the | ||
| legacy command: | ||
|
|
||
| .. code:: bash | ||
| $ tox run -e list | ||
| # or... | ||
| $ tox legacy -e list |