[internal] Rename ./pants lock to ./pants generate-user-lockfile and ./pants tool-lock to ./pants generate-lockfiles

[Eric-Arellano]

We currently have separate goals for user lockfiles vs tool lockfiles because the implementations are different right now, e.g. specs being different. It's easier to keep separate while iterating. We will unify them, but are not yet ready.

We want to release tool lockfiles as stable in Pants 2.7, so it should be using the final proper name of ./pants generate-lockfiles rather than ./pants tool-lock.

Once user lockfiles are stable in 2.8, we will kill generate-user-lockfile in favor of a unified generate-lockfiles goal.

generate-lockfiles vs. lock vs resolve vs. something else

See #12641 (comment) for why I went with generate-lockfiles, and the above thread for alternative proposals.

[ci skip-rust]
[ci skip-build-wheels]

[benjyw]

So the plan is that once user lockfiles are stable as a feature they too will use lock, and not user-lock ?

[Eric-Arellano]

Yes, exactly.

[cczona]

I know it's a lockfile, so lock makes a certain amount of sense. But as a purely semantic issue, I'm concerned that "lock" as a verb sounds like more potent security than what this is. For that reason, I'd vote for resolve or a fourth option.

[tdyas]

Rust uses cargo update.

[jsirois]

Why is it an explicit lock is even a goal long term? I may have missed that discussion. Presumably though, if I opt in to locks:

1. Any needed locks do not exist - I create them automatically as part of the rule chain that resolves things to achieve some other goal.
2. I run ./pants {update-locks, update, ...?} if I have locks and want to regenerate them (in part if we end up supporting that) or in whole.

[Eric-Arellano]

Good point @jsirois. Indeed, I think lock is possibly temporary as we punt on #12014. update-locks would make more sense than lock, similar to cargo update.

Still, in the meantime we have to choose lock vs resolve vs python-lock vs something else.

[kaos]

I'll just toss in my 2 cents here..

TL;DR;
My vote would be for update-lockfile.

Longer version:

I kind of like how make addresses this, so with that as inspiration, it would look like this

./pants make 3rdparty/python/locks/black.txt

However, "make" doesn't really fit well here.. so I think "update" makes more sense. "tool-lock" or just "lock" doesn't really signal to me that we're actually going to refresh the lock file. Maybe if the provided target was a requirements file, "lock" signals that taken the requirements, we lock them down, producing a lockfile. That has bearing in my head.

So, if the target is a lockfile, then "update" or "refresh" or something along those lines makes more sense imo. Could also consider the pip verb "freeze" (but that is arguably interchangeable with "lock").

Without any target however, a bare "update" doesn't cover it, then it would have to convey more in the goal verb itself, such as "update-lockfile" (I think using "lockfile" rather than just the shorter "lock" also gives a clearer picture of what it refers to, as "lock" is a bit too abstract).

Also, I think update-lockfile ought to work regardless of target language, so wouldn't have to add python in there, imo, as long as the implementation is able to discern what to do, based on the target lockfile itself.

[chrisjrn]

Why is it an explicit lock is even a goal long term? I may have missed that discussion. Presumably though, if I opt in to locks:

1. Any needed locks do not exist - I create them automatically as part of the rule chain that resolves things to achieve some other goal.
2. I run ./pants {update-locks, update, ...?} if I have locks and want to regenerate them (in part if we end up supporting that) or in whole.

Producing a user lockfile is producing an artefact that people will check into source control, which is not necessarily true of rule chains that resolve for other goals (yes for fmt, probably not for build).

I am less in favour of update-lockfile (or things that insofar as lockfiles may not already be in place when it's first run, but that may just be me overthinking things

[kaos]

[...] lockfiles may not already be in place when it's first run

Very good point.

I agree, that when a lockfile is not present, update doesn't really fit either.. (overlooked that scenario). So, what you guys feel for generate-lockfiles then..?
This goes the other way around, that in cases that the files do exist, it ought to rather be regenerate-lockfiles, however, simply "generate" can still work, if we treat the existing files as being discardable and of no concern, and that we simply replace them with the newly generated ones.

[chrisjrn]

continuing the bikeshedding: how about pin-dependencies?

[Eric-Arellano]

So, what you guys feel for generate-lockfiles then..?

I like it! I was typing up this proposal but had to leave for the doctor the same time you sent in your suggestion :)

Per comment in #12591 (comment), I think it's plausible we'll want to only have ./pants update-lockfiles in the future because generation is automatic. But for now, generate-lockfiles is more accurate than update-lockfiles because this is the only way to generate. We can deprecate generate-lockfiles in favor of update-lockfiles when all the required work is landed for those semantics.

I also like that there's no ambiguity what this will do, unlike a vague lock or resolve. This is hopefully not a goal you need to run frequently, so the extra length is fine imo.

Producing a user lockfile is producing an artefact that people will check into source control, which is not necessarily true of rule chains that resolve for other goals (yes for fmt, probably not for build).

@chrisjrn Once #12014 is figured out, running ./pants fmt will generate/update the relevant tool lockfiles if necessary as a side effect. This is how Cargo does things, and it works well.

[stuhood]

These longer generate-* names are fairly clearly temporary, so I'm fine with this until the semantics are nailed down.