Skip to content

Commit 12a2a8a

Browse files
sirosensirosen
committed
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
1 parent 8244a05 commit 12a2a8a

File tree

3 files changed

+144
-131
lines changed

3 files changed

+144
-131
lines changed

‎docs/faq.rst‎

Lines changed: 6 additions & 131 deletions
Original file line numberDiff line numberDiff line change
@@ -1,142 +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 - known regressions
52-
+++++++++++++++++++++++++
53-
54-
- With tox 4 the tty trait of the caller environment is no longer passed through. The most notable impact of this is
55-
that some tools no longer print colored output. A PR to address this is welcomed, in the meantime you can use the
56-
``tty`` substitution to force color mode for these tools, see for example tox itself with pytest and mypy
57-
`here in tox.ini <https://github.com/tox-dev/tox/blob/main/tox.ini#L28>`_.
58-
59-
tox 4 - new plugin system
60-
+++++++++++++++++++++++++
61-
62-
tox 4 is a grounds up rewrite of the code base, and while we kept the configuration layer compatibility no such effort
63-
has been made for the programmatic API. Therefore, all plugins will need to redo their integration against the new code
64-
base. If you're a plugin developer refer to the `plugin documentation <https://tox.wiki/en/latest/plugins.html>`_ for
65-
more information.
66-
67-
tox 4 - removed tox.ini keys
68-
++++++++++++++++++++++++++++
69-
70-
+--------------------------+----------------------------------------------+
71-
| Configuration key | Migration path |
72-
+==========================+==============================================+
73-
| ``indexserver`` | See `Using a custom PyPI server`_. |
74-
+--------------------------+----------------------------------------------+
75-
| ``whitelist_externals`` | Use :ref:`allowlist_externals` key instead. |
76-
+--------------------------+----------------------------------------------+
77-
| ``isolated_build`` | Isolated builds are now always used. |
78-
+--------------------------+----------------------------------------------+
79-
| ``distdir`` | Use the ``TOX_PACKAGE`` environment variable.|
80-
+--------------------------+----------------------------------------------+
81-
82-
tox 4 - basepython not resolved
83-
+++++++++++++++++++++++++++++++
84-
The base python configuration is no longer resolved to ``pythonx.y`` format, instead is kept as ``py39``, and is
85-
the virtualenv project that handles mapping that to a Python interpreter. If you were using this variable we recommend
86-
moving to the newly added ``py_impl`` and ``py_dot_ver`` variables, for example:
87-
88-
.. code-block:: ini
89-
90-
deps = -r{py_impl}{py_dot_ver}-req.txt
91-
92-
tox 4 - substitutions removed
93-
+++++++++++++++++++++++++++++
94-
- The ``distshare`` substitution has been removed.
95-
96-
tox 4 - disallowed env names
97-
++++++++++++++++++++++++++++
98-
- Environment names that contain multiple Python variants, such as ``name-py39-pypy`` or ``py39-py310`` will now raise
99-
an error, previously this only warned, you can use :ref:`ignore_basepython_conflict` to disable this error, but we
100-
recommend changing the name to avoid this name that can be confusing.
101-
102-
tox 4 - CLI arguments changed
103-
+++++++++++++++++++++++++++++
104-
- The ``--parallel--safe-build`` CLI argument has been removed, no longer needed.
105-
- When you want to pass an option to a test command, e.g. to ``pytest``, now you must use ``--`` as a separator, this
106-
worked with version 3 also, but any unknown trailing arguments were automatically passed through, while now this is
107-
no longer the case.
108-
- Running ``--showconfig`` or ``--help-ini`` with the ``-v`` flag will add interleaved debugging information, whereas
109-
tox 3 added additional lines at the start. If you want to generate valid ini files you must not use the ``-v`` flag.
110-
- The ``--index-url`` is now removed, use ``PIP_INDEX_URL`` in :ref:`set_env` instead.
111-
112-
tox 4 - packaging changes
113-
+++++++++++++++++++++++++
114-
- We use isolated builds (always) as specified by :pep:`518` and use :pep:`517` to communicate with the build backend.
115-
- The ``--develop`` CLI flag or the :ref:`use_develop` settings now enables editable installations via the :pep:`660`
116-
mechanism rather than the legacy ``pip install -e`` behaviour. The old functionality can still be forced by setting
117-
the :ref:`package` setting for the run environment to ``editable-legacy``.
118-
119-
tox 4 -- output changes
120-
+++++++++++++++++++++++
121-
- We now use colors for reporting, to help make the output easier to read for humans. This can be disabled via the
122-
``TERM=dumb`` or ``NO_COLOR=1`` environment variables, or the ``--colored no`` CLI argument.
123-
124-
tox 4 -- re-use of environments
125-
+++++++++++++++++++++++++++++++
126-
127-
- It is no longer possible to re-use environments. While this might have been possible with tox version 3, this
128-
behavior was never supported, and possibly caused wrong results as illustrated in the following example.
129-
130-
.. code-block:: ini
131-
132-
[testenv]
133-
envdir = .tox/venv
13410

135-
[testenv:a]
136-
deps = pytest>7
137-
138-
[testenv:b]
139-
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>`.
14013

14114
New features in tox 4
14215
---------------------
@@ -192,6 +65,8 @@ Here is a non-exhaustive list of these.
19265
label by using the ``-m label`` CLI flag (instead of the ``-e list_of_envs``).
19366
- You can now invoke all tox environments within a given factor via the ``-f factor`` CLI flag.
19467

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

0 commit comments

Comments
 (0)