What flag will users use to call the new resolver?

[ei8fdb]

What is the user story

As a pip user I need a way to use the optional new dependency resolver so that I can install my pip packages.

Additional context
Right now, in order to use the new alpha dependency resolver a pip user needs to use the flag:

--unstable-feature=resolver

to call the new resolver, instead of calling the old resolver. The old resolver will be maintained for a period of time, but ultimately it will go away.

How will the pip resolver behaviour change over time

1. the default will initially be the old resolver.
2. then it will change to be the new resolver
3. finally the old resolver will go away
4. the new resolver will be the only option

What we need to find out?

1. Can the current flag continue to be used until the old resolver goes away?
2. If the answer to 1 is no, what should the new flag be?

How can we do this out?
Research:

• how other pip commands have been rolled out
• how other CLI tools roll-out new internal functionality that replaces old
• what user research is needed?
• what design work is needed?

What we need to do this design or research

• talk with maintainers
• talk with pip users

Are there possible solutions?
The goal is we want to choose an "answer that won't infuriate our users because they keep having to change scripts, or because the approach we choose otherwise imposes on their workflow in unnecessary ways."

Best practices would be to maintain consistency in the pip CLI. Must discuss more.

[brainwane]

We're discussing this in Zulip as well.

[brainwane]

TL;DR: we're going to use a new flag: --resolver=. We're figuring out now what will go on the other side of that equal sign.

I appreciate the work @ei8fdb has done to lay out this question and problem, and the work he and @pradyunsg and @pfmoore have done in Zulip to figure out what we will do.

Paul suggested:

1. We call the new flag --resolver=backtracking. The old resolver is --resolver=legacy.
2. We introduce --resolver as part of the "main rollout", which we do in June. The default will be legacy at that point.
3. We immediately remove --unstable-feature=resolver at that point, with no deprecation, as no-one should be using it for anything except manual testing anyway. We leave the machinery for --unstable-feature in place, but we drop the resolver option (so leaving us as having no actual unstable features).
4. At some to-be-decided point, we switch the default for --resolver from legacy to backtracking. We warn for a period of one release before making that change.
5. At a second to-be-decided point, we remove the legacy resolver code and the legacy option for --resolver. We again warn for one release before doing this.

There's quite a lot of work to implement this (test suite changes to handle the new flags, the actual flag code, etc). So we can't leave it too long to get this agreed.

I approve that general approach and in particular I approve the --resolver= flag, and the approach of replacing --unstable-feature= with --resolver= WITHOUT a one-release deprecation period.

So we can get started on that right away.

But I do want to take another day to refine the words we use on the right-hand side of that equal sign, the labels for different resolvers.

@ei8fdb refined this by suggesting, in the interest of using plain language that users are more likely to be familiar with:

Instead of the new resolver being -resolver=backtracking make it -resolver=beta
Instead of the old resolver being --resolver=legacy make it --resolver=old

@pradyunsg noted:

IMO, if a user is using the beta of the new implementation, and they upgrade to a newer version of pip where it's considered stable (or the default), they shouldn't need to change their CI. In other words, we shouldn't create extra work for early adopters once the feature goes stable. I'm not sure how that would work with an =beta approach.

I understand what Pradyun is saying. It's a good reason not to use the word "beta" here. But "backtracking" is a word that does not carry useful meaning for most people who use pip. So I'm thinking about a replacement word. Something plain-language that describes an important attribute of the resolver without only talking about newness.

I will sleep on this and have more suggestions in the morning. I am open to suggestions, but I want to avoid people talking back-and-forth and bikeshedding each other's suggestions; in the next 24 hours, if you have a suggestion, you can make it in this thread, but and you can make one reply to someone else's suggestion, but try not to reply again after that.

[pradyunsg]

"v2", "2020-rewrite" are two ideas.

I know I've brought up "new" in the past, but it'd likely be better to avoid that, so that we don't end up with a new new resolver at some point in the future. :)

[sbidoul]

legacy|backtracking is fine with me. Have you considered legacy|resolvelib?

[pfmoore]

Have you considered legacy|resolvelib?

I considered suggesting that, but there was talk about replacing resolvelib with PubGrub at some point, and I wasn't sure if that would need a new option, or would be considered "transparent". (And PubGrub is an even worse term, in terms of being obscure jargon...)

[nlhkabu]

I'm not sure that we're not just creating a whole lot more work for ourselves here?

My 2c:

• I think we should keep using --unstable-feature=resolver until the resolver is ready for prod.
• When it is ready, we should make the new resolver the default, and make the old resolver available under --deprecated-feature=resolver
• I am strongly against referencing the technical implementation in the command. the terms resolvelib and pubgrub mean absolutely nothing to the majority of pip users.

My thinking:

1. We have just done a big program of community outreach asking people to test the new resolver with --unstable-feature=resolver. If we decide to get rid of this command, we will have to do another round of communication. Inevitably, some people will not realise that this command is no longer available and become frustrated.

2. I have absolutely no issue with keeping the word "unstable" in the command. IMO, if it is not ready for use in production, then it is, by definition, unstable. We should not be embarrassed by this, or let it detract from the great work the team is doing.

3. I assume that the --unstable-feature flag was introduced as a process to deal with rolling out any new feature in future. By creating a new --resolver flag, we are undermining that process.

4. By introducing a --deprecated-feature flag we can create a universal process for deprecating features, that can be used again in future

Pros of this plan:

• The clearest path for pip users, given our previous community outreach
• The least amount of work for the team
• Reusable for future features

Cons:

• Not specific to the resolver
• Does not allow us to communicate different levels of readiness: the resolver is either unstable or ready for prod, there is no in-between.

[ei8fdb]

Does not allow us to communicate different levels of readiness: the resolver is either unstable or ready for prod, there is no in-between.

To communicate these different levels of readiness, I've seen the following communications working well:

• clearly written release-note
• public communications (in this case to lists/twitter/podcasts)

If a user never sees these communications - when a user updates pip, they get automatically the newest version of the feature.

If they don't upgrade - there is no difference anyway, they're still on the same version.

(For future features this strategy could also be used for communication of alpha/beta releases)

[uranusjr]

"v2", "2020-rewrite" are two ideas.

--resolver=2020 seems to read OK as well.

[brainwane]

I thought I could make a decision to make things easier for everyone, but @nlhkabu has persuaded me that I was wrong.

My current thinking is that we should go with the plan @nlhkabu has laid out, using

--unstable-feature=resolver

and then

--deprecated-feature=resolver

and I think we should make sure to get a final decision on this in tomorrow's meeting.

Heads-up to @dstufft @xavfernandez @cjerdonek @chrahunt and @dholth -- I'd appreciate if you could look at this discussion and share your opinion. However, we have a team meeting scheduled for about 14.5 hours from now, 9am-10am Eastern time, and I'd like to have this question decided by the end of that meeting so that everyone can implement it. So if you want to join in that meeting please message me and I'll get you the info to join it.