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