Document ambiguous usages in v3-to-v4 #2808
Conversation
Add a section to the upgrading doc, "Legacy CLI entry point may result in ambiguous usages" The new section resolves tox-dev#2728
|
|
||
| .. code:: bash | ||
|
|
||
| $ tox run -e list |
There was a problem hiding this comment.
For what's worth this is my recommended way to run unambiguous command names too, so let's State that. Assuming legacy by default is just a backwards compatibility layer and might be removed with tox 5.
There was a problem hiding this comment.
Worth mentioning that you don't have to type run fully, the r letter acts as a shorter alias 👍
There was a problem hiding this comment.
Okay, I'll come back to you with something that states that more clearly, and we can wordsmith it more if necessary.
There was a problem hiding this comment.
In order to put this front-and-center, I decided to split the section up a little more.
First it states that you should rewrite any use of tox -e foo to tox run -e foo/tox r -e foo without trying to explain why. The second subsection focuses on the bad case of an environment matching a command name.
Hope you like it this way!
docs/upgrading.rst
Outdated
| @@ -149,3 +149,51 @@ Re-use of environments | |||
|
|
|||
| [testenv:b] | |||
| deps = pytest<7 | |||
|
|
|||
|
|
|||
| Legacy CLI entry point may result in ambiguous usages | |||
There was a problem hiding this comment.
Probably should be shorter: CLI compatibility is enough.
There was a problem hiding this comment.
There's another section on "CLI arguments", so I called it "CLI command compatibility", but we could also combine the sections later maybe.
Retitle the section. Split it into two subsections, one on ``-e`` vs ``run -e``, and one on command names matching environments (as a specific case).
This PR contains the following updates: | Package | Type | Update | Change | Pending | |---|---|---|---|---| | [tox](https://github.com/tox-dev/tox) ([changelog](https://tox.wiki/en/latest/changelog.html)) | dev | minor | `4.1.3` -> `4.2.0` | `4.3.4` (+12) | --- ### Release Notes <details> <summary>tox-dev/tox</summary> ### [`v4.2.0`](https://github.com/tox-dev/tox/releases/tag/4.2.0) [Compare Source](https://github.com/tox-dev/tox/compare/4.1.3...4.2.0) #### What's Changed - Introduce Upgrading doc page for tox4 by [@​sirosen](https://github.com/sirosen) in [https://github.com/tox-dev/tox/pull/2805](https://github.com/tox-dev/tox/pull/2805) - Document ambiguous usages in v3-to-v4 by [@​sirosen](https://github.com/sirosen) in [https://github.com/tox-dev/tox/pull/2808](https://github.com/tox-dev/tox/pull/2808) - Packaging inherits from pkgenv, deps and document tox 4 packaging changes by [@​gaborbernat](https://github.com/gaborbernat) in [https://github.com/tox-dev/tox/pull/2813](https://github.com/tox-dev/tox/pull/2813) **Full Changelog**: tox-dev/tox@4.1.3...4.2.0 </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Enabled. ♻ **Rebasing**: Whenever PR is behind base branch, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box <!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiIzNC45OS4yIiwidXBkYXRlZEluVmVyIjoiMzQuOTkuMiJ9--> Co-authored-by: descope[bot] <descope[bot]@users.noreply.github.com>
Add a section to the upgrading doc, "Legacy CLI entry point may result in ambiguous usages"
The new section resolves #2728
Upon review, I'm not sure if this should be written as "ambiguous usages" or "environments whose names match subcommands". I'm open to renaming or rewriting it as appropriate.