https://pantsbuild.org/ logo
#development
Title
# development
h

hundreds-father-404

03/10/2022, 9:47 PM
Hey alternative angle for Pants 2.10 third-party dependency management...
I've been trying to write the docs for two weeks now, and it's so confusing because we have four ways of doing things 1) no locks 2) constraints file, which must be manually generated 3) resolves + generate-lockfiles goal 4) resolves + manual generation What if we stop documenting 2 in favor of always using 3 and 4? Note that 2 and 4 are very similar - because it's manually generated, you can do things like leave off
--hash
, meaning that VCS requirements can be supported. If you're using
[python-repos]
, you already had to wire that up properly to your manual lockfile generation! Nothing new. The only change from 2 and 4 is that Pants is stricter. Your lockfile must be comprehensive. Whereas with 2, Pex will fill in any unpinned transitive deps for you. And with 2, any missing direct deps will cause Pants to not use constraints.txt like a lockfile->repository.pex, instead behaving like approach 1) of no locks but with
--constraints
set. I'm proposing that we document 3) as the ideal, but heavily document you may run into issues like
[python-repos]
and the transitive deps issue. As a result, many users will need to use approach 4)
No deprecations yet for Pants code - this is only how we document things, including example-python repo
This largely comes from advice from @busy-vase-39202 about the WIP docs I have at https://www.pantsbuild.org/v2.10/docs/3rd-party-rewrite#lockfiles that talk about Constraints.txt vs resolves feature
Hard to tell without the content there. My gut instinct says if you present more than one way to something, be opinionated about when each is best applied. Otherwise it's just a new user hitting a stumbling block of trying to figure out whether to zig or zag.
I agree it's confusing to describe when to use overall lock technology. Whereas now it's only how those lockfiles get generated
💯 1
e

enough-analyst-54434

03/10/2022, 9:53 PM
If it's hard to write about is that a sign to not do so? Presumably it will be easier when we have a more whole product.
h

hundreds-father-404

03/10/2022, 9:55 PM
Oh! Another benefit of only talking about approaches 3 and 4 is that we can improve our docs on tool lockfiles. They blatantly leave off that
[python-repos]
and VCS does not work, which has tripped up people
If it's hard to write about is that a sign to not do so?
Iirc we've now had 3-4 users in the past 3 weeks who needed to use multiple lockfiles. I believe the majority of them used manual generation - not great, but better than status quo That suggests to me as incomplete as this feature is, it's better than the status quo and users want to know about.
e

enough-analyst-54434

03/10/2022, 9:56 PM
Hrm. I guess. I think it would be good to do a postmortem on all this here in a few months.
w

witty-crayon-22786

03/10/2022, 9:56 PM
What if we stop documenting 2 in favor of always using 3 and 4?
this sounds very reasonable, yea. migrating from 2 to 4 is still a step that heads in the right direction (toward 3, when that’s possible for ~everyone in
2.11.x
)
👍 1
h

hundreds-father-404

03/10/2022, 9:57 PM
when that’s possible for ~everyone in 2.11.x)
Possible for everyone but VCS users, most likely. So Pants 2.11 will still talk about approaches 3 and 4, but many more people can use 3 than they can now
w

witty-crayon-22786

03/10/2022, 9:58 PM
yea.
h

hundreds-father-404

03/10/2022, 9:59 PM
Cool I will do this rewrite on https://www.pantsbuild.org/v2.10/docs/3rd-party-rewrite#lockfiles first to get final approval, then copy over to our main docs after. Thank you
I think it would be good to do a postmortem on all this here in a few months.
That'd be fruitful. Original sin is abusing constraints file way back in Pants 2.2 or whenever that was.
w

witty-crayon-22786

03/10/2022, 10:03 PM
and yet, not having lockfiles for a year wouldn’t have been viable either… *shrug. but yea, always good to retrospect.
👍 1
e

enough-analyst-54434

03/10/2022, 10:05 PM
I'm having a hard time shrugging off all the pain myself.
1
b

bitter-ability-32190

03/11/2022, 12:09 PM
I'm +1 on this as well. Assuming there's at least some part of the docs that helps me get to 4 from my own pip-style lockfile (that
pex
command we talked about)
h

hundreds-father-404

03/14/2022, 11:50 PM
@witty-crayon-22786 @busy-vase-39202 thoughts on a dedicated blog now that we're deciding to lean into multiple resolves in 2.10? It's making the release blog pretty big https://docs.google.com/document/d/1rNkK8ToLMvTv4rXq_qUwvkXOcPxVYTZigaUnUhOsFNg/edit#
b

busy-vase-39202

03/14/2022, 11:54 PM
It's a tossup. If you can make the summary for the release notes considerably shorter, yes I think it'd be preferrable to let the details breathe in a dedicated post. But does it lend itself to that much condensing?
h

happy-kitchen-89482

03/14/2022, 11:54 PM
Blog posts can be short, so I'd say yes!
b

busy-vase-39202

03/14/2022, 11:55 PM
(fwiw: a dedicated post is easier to link people to later, and I expect this to be a topic we want to do that with. So my preference is for separate post.)
h

hundreds-father-404

03/14/2022, 11:55 PM
It sounds like 2.10 is where we talk about Pants's lockfile strategy overall, whereas 2.11 would be focused on Pex lockfile generation (if it's ready). So I think a dedicated post makes sense
👍 1