Skip to content

Commit 031e902

Browse files
sirosensirosen
authored
Introduce Upgrading doc page for tox4 (#2805)
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.
1 parent d05ea02 commit 031e902

File tree

3 files changed

+158
-134
lines changed

3 files changed

+158
-134
lines changed

‎docs/faq.rst‎

Lines changed: 6 additions & 134 deletions
Original file line numberDiff line numberDiff line change
@@ -1,145 +1,15 @@
1+
.. _faq:
2+
13
FAQ
24
===
35

46
Here you'll find answers to some frequently asked questions.
57

68
Breaking changes in tox 4
79
-------------------------
8-
Version 4 of tox should be mostly backwards compatible with version 3, with the following exceptions:
9-
10-
tox 4 - Python support
11-
++++++++++++++++++++++
12-
- tox now requires Python ``3.7`` or later and is tested only against CPython. You can still create test environments
13-
for earlier Python versions or different Python interpreters. PyPy support is best effort, meaning we do not test it
14-
as part of our CI runs, however if you discover issues under PyPy we will accept PRs addressing it.
15-
16-
tox 4 - changed INI rules
17-
+++++++++++++++++++++++++
18-
- The hash sign (``#``) now always acts as comment within ``tox.ini`` or ``setup.cfg`` tox configuration file. Where you
19-
need to pass on a ``#`` character you will need to escape it in form of ``\#`` so tox does not handle everything right
20-
of the ``#`` character as a comment. Valid in tox 3:
21-
22-
.. code-block:: ini
23-
24-
# valid in tox 3
25-
commands = bash -c "echo 'foo#bar'"
26-
27-
# valid in tox 4
28-
commands = bash -c "echo 'foo\#bar'"
29-
30-
- Within the ``pass_env`` you can no longer use space as value separator, instead you need to use the ``,`` or the
31-
newline character. This is to have the same value separation rules for all tox configuration lines.
32-
33-
.. code-block:: ini
34-
35-
# valid in tox 3
36-
passenv = ALPHA BETA
37-
passenv =
38-
ALPHA
39-
BETA
40-
41-
# valid in tox 4
42-
passenv = ALPHA, BETA
43-
passenv =
44-
ALPHA
45-
BETA
46-
47-
- tox 4 now errors when using the ``-U`` flag when defining dependencies, e.g. ``deps = -Ur requirements.txt``. While
48-
this worked in tox 3, it was never supported officially. Additionally, in the context of a new virtual environment
49-
this flag makes no sense anyway.
50-
51-
- tox 4 requires the ``install_command`` to evaluate to a non-empty value for each target environment. In tox 3, an
52-
empty value would be substituted for the default install command.
53-
54-
tox 4 - known regressions
55-
+++++++++++++++++++++++++
56-
57-
- With tox 4 the tty trait of the caller environment is no longer passed through. The most notable impact of this is
58-
that some tools no longer print colored output. A PR to address this is welcomed, in the meantime you can use the
59-
``tty`` substitution to force color mode for these tools, see for example tox itself with pytest and mypy
60-
`here in tox.ini <https://github.com/tox-dev/tox/blob/main/tox.ini#L28>`_.
61-
62-
tox 4 - new plugin system
63-
+++++++++++++++++++++++++
64-
65-
tox 4 is a grounds up rewrite of the code base, and while we kept the configuration layer compatibility no such effort
66-
has been made for the programmatic API. Therefore, all plugins will need to redo their integration against the new code
67-
base. If you're a plugin developer refer to the `plugin documentation <https://tox.wiki/en/latest/plugins.html>`_ for
68-
more information.
69-
70-
tox 4 - removed tox.ini keys
71-
++++++++++++++++++++++++++++
72-
73-
+--------------------------+----------------------------------------------+
74-
| Configuration key | Migration path |
75-
+==========================+==============================================+
76-
| ``indexserver`` | See `Using a custom PyPI server`_. |
77-
+--------------------------+----------------------------------------------+
78-
| ``whitelist_externals`` | Use :ref:`allowlist_externals` key instead. |
79-
+--------------------------+----------------------------------------------+
80-
| ``isolated_build`` | Isolated builds are now always used. |
81-
+--------------------------+----------------------------------------------+
82-
| ``distdir`` | Use the ``TOX_PACKAGE`` environment variable.|
83-
+--------------------------+----------------------------------------------+
84-
85-
tox 4 - basepython not resolved
86-
+++++++++++++++++++++++++++++++
87-
The base python configuration is no longer resolved to ``pythonx.y`` format, instead is kept as ``py39``, and is
88-
the virtualenv project that handles mapping that to a Python interpreter. If you were using this variable we recommend
89-
moving to the newly added ``py_impl`` and ``py_dot_ver`` variables, for example:
90-
91-
.. code-block:: ini
92-
93-
deps = -r{py_impl}{py_dot_ver}-req.txt
94-
95-
tox 4 - substitutions removed
96-
+++++++++++++++++++++++++++++
97-
- The ``distshare`` substitution has been removed.
98-
99-
tox 4 - disallowed env names
100-
++++++++++++++++++++++++++++
101-
- Environment names that contain multiple Python variants, such as ``name-py39-pypy`` or ``py39-py310`` will now raise
102-
an error, previously this only warned, you can use :ref:`ignore_basepython_conflict` to disable this error, but we
103-
recommend changing the name to avoid this name that can be confusing.
104-
105-
tox 4 - CLI arguments changed
106-
+++++++++++++++++++++++++++++
107-
- The ``--parallel--safe-build`` CLI argument has been removed, no longer needed.
108-
- When you want to pass an option to a test command, e.g. to ``pytest``, now you must use ``--`` as a separator, this
109-
worked with version 3 also, but any unknown trailing arguments were automatically passed through, while now this is
110-
no longer the case.
111-
- Running ``--showconfig`` or ``--help-ini`` with the ``-v`` flag will add interleaved debugging information, whereas
112-
tox 3 added additional lines at the start. If you want to generate valid ini files you must not use the ``-v`` flag.
113-
- The ``--index-url`` is now removed, use ``PIP_INDEX_URL`` in :ref:`set_env` instead.
114-
115-
tox 4 - packaging changes
116-
+++++++++++++++++++++++++
117-
- We use isolated builds (always) as specified by :pep:`518` and use :pep:`517` to communicate with the build backend.
118-
- The ``--develop`` CLI flag or the :ref:`use_develop` settings now enables editable installations via the :pep:`660`
119-
mechanism rather than the legacy ``pip install -e`` behaviour. The old functionality can still be forced by setting
120-
the :ref:`package` setting for the run environment to ``editable-legacy``.
121-
122-
tox 4 -- output changes
123-
+++++++++++++++++++++++
124-
- We now use colors for reporting, to help make the output easier to read for humans. This can be disabled via the
125-
``TERM=dumb`` or ``NO_COLOR=1`` environment variables, or the ``--colored no`` CLI argument.
126-
127-
tox 4 -- re-use of environments
128-
+++++++++++++++++++++++++++++++
129-
130-
- It is no longer possible to re-use environments. While this might have been possible with tox version 3, this
131-
behavior was never supported, and possibly caused wrong results as illustrated in the following example.
132-
133-
.. code-block:: ini
134-
135-
[testenv]
136-
envdir = .tox/venv
13710

138-
[testenv:a]
139-
deps = pytest>7
140-
141-
[testenv:b]
142-
deps = pytest<7
11+
Version 4 of tox should be mostly backwards compatible with version 3.
12+
Exceptions and guidance for migrating are given in the :ref:`upgrading doc <upgrading>`.
14313

14414
New features in tox 4
14515
---------------------
@@ -195,6 +65,8 @@ Here is a non-exhaustive list of these.
19565
label by using the ``-m label`` CLI flag (instead of the ``-e list_of_envs``).
19666
- You can now invoke all tox environments within a given factor via the ``-f factor`` CLI flag.
19767

68+
.. _faq_custom_pypi_server:
69+
19870
Using a custom PyPI server
19971
--------------------------
20072
By default tox uses pip to install Python dependencies. Therefore to change the index server you should configure pip

‎docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,3 +76,4 @@ you want to do more research, we recommend taking a look at these projects:
7676
plugins_api
7777
development
7878
changelog
79+
upgrading

‎docs/upgrading.rst‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
.. _upgrading:
2+
3+
Upgrading to tox v4
4+
===================
5+
6+
Version 4 is mostly backwards compatible.
7+
This document covers all breaking changes and, where applicable, includes guidance on how to update.
8+
9+
See also the list of new features in the :ref:`FAQ <faq>`.
10+
11+
Python support
12+
--------------
13+
14+
- tox now requires Python ``3.7`` or later and is tested only against CPython. You can still create test environments
15+
for earlier Python versions or different Python interpreters. PyPy support is best effort, meaning we do not test it
16+
as part of our CI runs, however if you discover issues under PyPy we will accept PRs addressing it.
17+
18+
Changed INI rules
19+
-----------------
20+
21+
- The hash sign (``#``) now always acts as comment within ``tox.ini`` or ``setup.cfg`` tox configuration file. Where you
22+
need to pass on a ``#`` character you will need to escape it in form of ``\#`` so tox does not handle everything right
23+
of the ``#`` character as a comment. Valid in tox 3:
24+
25+
.. code-block:: ini
26+
27+
# valid in tox 3
28+
commands = bash -c "echo 'foo#bar'"
29+
30+
# valid in tox 4
31+
commands = bash -c "echo 'foo\#bar'"
32+
33+
- Within the ``pass_env`` you can no longer use space as value separator, instead you need to use the ``,`` or the
34+
newline character. This is to have the same value separation rules for all tox configuration lines.
35+
36+
.. code-block:: ini
37+
38+
# valid in tox 3
39+
passenv = ALPHA BETA
40+
passenv =
41+
ALPHA
42+
BETA
43+
44+
# valid in tox 4
45+
passenv = ALPHA, BETA
46+
passenv =
47+
ALPHA
48+
BETA
49+
50+
- tox 4 now errors when using the ``-U`` flag when defining dependencies, e.g. ``deps = -Ur requirements.txt``. While
51+
this worked in tox 3, it was never supported officially. Additionally, in the context of a new virtual environment
52+
this flag makes no sense anyway.
53+
54+
- tox 4 requires the ``install_command`` to evaluate to a non-empty value for each target environment. In tox 3, an
55+
empty value would be substituted for the default install command.
56+
57+
Known regressions
58+
-----------------
59+
60+
- With tox 4 the tty trait of the caller environment is no longer passed through. The most notable impact of this is
61+
that some tools no longer print colored output. A PR to address this is welcomed, in the meantime you can use the
62+
``tty`` substitution to force color mode for these tools, see for example tox itself with pytest and mypy
63+
`here in tox.ini <https://github.com/tox-dev/tox/blob/main/tox.ini#L28>`_.
64+
65+
New plugin system
66+
-----------------
67+
68+
tox 4 is a grounds up rewrite of the code base, and while we kept the configuration layer compatibility no such effort
69+
has been made for the programmatic API. Therefore, all plugins will need to redo their integration against the new code
70+
base. If you're a plugin developer refer to the `plugin documentation <https://tox.wiki/en/latest/plugins.html>`_ for
71+
more information.
72+
73+
Removed tox.ini keys
74+
--------------------
75+
76+
+--------------------------+-----------------------------------------------------------------+
77+
| Configuration key | Migration path |
78+
+==========================+=================================================================+
79+
| ``indexserver`` | See :ref:`Using a custom PyPI server <faq_custom_pypi_server>`. |
80+
+--------------------------+-----------------------------------------------------------------+
81+
| ``whitelist_externals`` | Use :ref:`allowlist_externals` key instead. |
82+
+--------------------------+-----------------------------------------------------------------+
83+
| ``isolated_build`` | Isolated builds are now always used. |
84+
+--------------------------+-----------------------------------------------------------------+
85+
| ``distdir`` | Use the ``TOX_PACKAGE`` environment variable. |
86+
+--------------------------+-----------------------------------------------------------------+
87+
88+
basepython not resolved
89+
-----------------------
90+
91+
The base python configuration is no longer resolved to ``pythonx.y`` format, instead is kept as ``py39``, and is
92+
the virtualenv project that handles mapping that to a Python interpreter. If you were using this variable we recommend
93+
moving to the newly added ``py_impl`` and ``py_dot_ver`` variables, for example:
94+
95+
.. code-block:: ini
96+
97+
deps = -r{py_impl}{py_dot_ver}-req.txt
98+
99+
Substitutions removed
100+
---------------------
101+
102+
- The ``distshare`` substitution has been removed.
103+
104+
Disallowed env names
105+
--------------------
106+
107+
- Environment names that contain multiple Python variants, such as ``name-py39-pypy`` or ``py39-py310`` will now raise
108+
an error, previously this only warned, you can use :ref:`ignore_basepython_conflict` to disable this error, but we
109+
recommend changing the name to avoid this name that can be confusing.
110+
111+
CLI arguments changed
112+
---------------------
113+
114+
- The ``--parallel--safe-build`` CLI argument has been removed, no longer needed.
115+
- When you want to pass an option to a test command, e.g. to ``pytest``, now you must use ``--`` as a separator, this
116+
worked with version 3 also, but any unknown trailing arguments were automatically passed through, while now this is
117+
no longer the case.
118+
- Running ``--showconfig`` or ``--help-ini`` with the ``-v`` flag will add interleaved debugging information, whereas
119+
tox 3 added additional lines at the start. If you want to generate valid ini files you must not use the ``-v`` flag.
120+
- The ``--index-url`` is now removed, use ``PIP_INDEX_URL`` in :ref:`set_env` instead.
121+
122+
Packaging changes
123+
-----------------
124+
125+
- We use isolated builds (always) as specified by :pep:`518` and use :pep:`517` to communicate with the build backend.
126+
- The ``--develop`` CLI flag or the :ref:`use_develop` settings now enables editable installations via the :pep:`660`
127+
mechanism rather than the legacy ``pip install -e`` behaviour. The old functionality can still be forced by setting
128+
the :ref:`package` setting for the run environment to ``editable-legacy``.
129+
130+
Output changes
131+
--------------
132+
133+
- We now use colors for reporting, to help make the output easier to read for humans. This can be disabled via the
134+
``TERM=dumb`` or ``NO_COLOR=1`` environment variables, or the ``--colored no`` CLI argument.
135+
136+
Re-use of environments
137+
----------------------
138+
139+
- It is no longer possible to re-use environments. While this might have been possible with tox version 3, this
140+
behavior was never supported, and possibly caused wrong results as illustrated in the following example.
141+
142+
.. code-block:: ini
143+
144+
[testenv]
145+
envdir = .tox/venv
146+
147+
[testenv:a]
148+
deps = pytest>7
149+
150+
[testenv:b]
151+
deps = pytest<7

0 commit comments

Comments
 (0)