Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Show the default version of built-in (Python) tools in docs somewhere #20722

Closed
huonw opened this issue Mar 25, 2024 · 1 comment · Fixed by #20901
Closed

Show the default version of built-in (Python) tools in docs somewhere #20722

huonw opened this issue Mar 25, 2024 · 1 comment · Fixed by #20901
Assignees
@krishnan-chandra
Labels
backend: Python Python backend-related issues bug category:documentation documentation

Comments

@huonw
Copy link
Contributor

huonw commented Mar 25, 2024 •
edited

Describe the bug

Currently the default version of a Python tool built-in to Pants (like black) doesn't seem to be shown in the documentation anywhere, it's just implied by the lockfile, which is hidden: e.g. https://www.pantsbuild.org/2.19/reference/subsystems/black

(Compare a JVM tool like openapi-generator which has a default value for the version field: https://www.pantsbuild.org/2.19/reference/subsystems/openapi-generator#version)

This leads to confusion when newer releases of a tool change behaviour, deprecate options or even introduce new ones (like #20707) and a user can't tell why their configuration isn't working when run with Pants.

Suggestion: have PythonToolRequirementsBase dynamically argument the subsystem's help text by reading the lockfile. For instance, for the page above, adding the second paragraph in:

The Black Python code formatter (https://black.readthedocs.io/).

This version of Pants uses Black 23.3.0 by default. Use a dedicated lockfile and the install_from_resolve option to control this.

This could potentially also be applied to the install_from_resolve and/or requirements fields.

Pants version
2.19

OS
N/A

Additional info
N/A
@huonw huonw mentioned this issue Mar 25, 2024
Closed
@krishnan-chandra krishnan-chandra self-assigned this Apr 21, 2024
@krishnan-chandra
Copy link
Contributor

Happy to take this one! Assigned to myself

This was referenced May 10, 2024
Merged
Closed
huonw added a commit that referenced this issue May 13, 2024
@krishnan-chandra @huonw
Add tool version into install_from_resolve arg documentation (#20901)
794d0d4 
Closes #20722. Here's what the new output looks like:

```bash
./pants help black

`black` subsystem options
-------------------------

The Black Python code formatter (https://black.readthedocs.io/).
This version of Pants uses black 23.3.0 by default. Use a dedicated lockfile and the install_from_resolve option to control this.

...
```

I couldn't work out how to test this except by running the CLI to
generate the description (see above). And that...seems to work?

---------

Co-authored-by: Huon Wilson <wilson.huon@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@krishnan-chandra krishnan-chandra

Labels
backend: Python Python backend-related issues bug category:documentation documentation
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Add tool version into install_from_resolve arg documentation krishnan-chandra/pants
2 participants
@huonw @krishnan-chandra