Version specification in main text of tutorials/pyproject-toml.md
#191
Conversation
… specifications throughout, specific poetry example
| @@ -303,31 +338,30 @@ readme = "README.md" | |||
| license = {file = 'LICENSE'} | |||
| requires-python = ">=3.10" | |||
|
|
|||
| dependencies = ["numpy", "requests", "pandas", "pydantic"] | |||
| dependencies = ["numpy>=1.0", "requests==10.1", "pandas", "pydantic>=1.7,<2"] | |||
There was a problem hiding this comment.
@sneakers-the-rat one thing i think users will get stuck on here is how do they know what minimum version of a tool a package supports? i'm not sure how we'd explain that. it's not trivial because normally if you are new to software dev you are just installing tools and you won't do any pinning or lower or upper bound entries at all (unless you use poetry which has defaults). So how would i know (as a scientist who is a beginner to creating a package) that my tool can't support numpy < 1.0
There was a problem hiding this comment.
so this comment is really about adding some direction to a scientist on how to figure this out. rather than telling them to use a lower bounds with out any guidance as to how to do it.
There was a problem hiding this comment.
I typically set to the lower bound to the version that I create the package with. Described in another comment.
There was a problem hiding this comment.
Yeah I initially had that in here but took it out bc i didn't want to be too verbose, but if this is a sticking point then yes :). poetry at least does this automatically with poetry add, same with pdm add. i'm sort of surprised that hatch doesn't seem to have a cli command to add a dependency.
There was a problem hiding this comment.
@sneakers-the-rat I think if we choose the greater than current numpy version and make the comment: "Greater than or equal to the current version" that might clarify for @lwasser's concern.
There was a problem hiding this comment.
yes this would absolutely clarify my concern. i think this is important to add but also guiding a user through how to pick the minimum version would be great. Currently using hatch, it does not support this feature (yet i think anyway) but i'm pretty sure ofek plans to add something like this? or that locking and deps are in the future of hatch's tooling. if you could add this clarification that would be great. @sneakers-the-rat
| @@ -370,7 +404,7 @@ readme = "README.md" | |||
| license = {file = 'LICENSE'} | |||
| requires-python = ">=3.10" | |||
|
|
|||
| dependencies = ["numpy", "requests", "pandas", "pydantic"] | |||
| dependencies = ["numpy>=1.0", "requests==10.1", "pandas", "pydantic>=1.7,<2"] | |||
There was a problem hiding this comment.
yes so here - i know pydantic well at this point. below 2.0 makes sense. but why did you pick 1.7 as the lower bound? and why doesn't pandas have any bounds?
There was a problem hiding this comment.
just random numbers to illustrate the version syntax :) - showing you can do exact pins, lower bounds, ranges, or unspecified - let me add some annotations to make that explicit
There was a problem hiding this comment.
awesome. yes that clarification would be great. for instance the pydantic <2 makes a ton of sense
|
@lwasser @sneakers-the-rat How would you like to reboot this PR? I'm happy to add and commit the suggestions which will likely fix the merge conflict. |
|
oop sorry accidentally marked as read. i can fix merge conflict and accept suggestions! |
thank you @willingc! Co-authored-by: Carol Willing <[email protected]>
Co-authored-by: Carol Willing <[email protected]>
| @@ -303,31 +338,30 @@ readme = "README.md" | |||
| license = {file = 'LICENSE'} | |||
| requires-python = ">=3.10" | |||
|
|
|||
| dependencies = ["numpy", "requests", "pandas", "pydantic"] | |||
| dependencies = ["numpy>=1.0", "requests==10.1", "pandas", "pydantic>=1.7,<2"] | |||
There was a problem hiding this comment.
@sneakers-the-rat I think if we choose the greater than current numpy version and make the comment: "Greater than or equal to the current version" that might clarify for @lwasser's concern.
|
ok i'll put this PR in my task list for tomorrow / monday to re-review. thank you all for this. @sneakers-the-rat another great addition to our guide here. thank you! |
lwasser
added
🚀 ready-for-review
enhancement-feature
There was a problem hiding this comment.
@sneakers-the-rat once again so sorry for the slow response. i've been so focused on our training coming up. This is a GREAT pr with really useful updates. let's merge it.
if i haven't told you this lately, i'm SO appreciative of all that you contribute to pyOpenSci. i've learned so much from you being here!! thank you.
Currently version specifiers are just in an admonition, and the examples all use dependency specifiers without versions. I think it's important to model version specification in the tutorials, since they probably won't see many real packages with wide open version specifiers in the wild, and they are the things that are the most troublesome/require the most maintenance over time/will be the source of the most bugs if left without version spec.
Currently
This PR
After the unchanged start of the section...
So now the "pin dependencies with caution" is just about pinning and narrow version constraints, and it also has a specific example for poetry, and the main text has a discussion about version specification.
I also changed the
dependenciesarray throughout to match.Something that newbies will also experience (i mean i am currently dealing with a problem like this) some cryptic messages about version incompatibility from
requires-pythonsaying they need to add an upper bound. I added a quick note there saying that lower bounds are just one way to specify it, but that you can use the more general version spec syntax there.IDK why gh's syntax highlighter is showing everything as red...