Document the new resolver

What’s the problem this feature will solve? Lots of people are getting frustrated with long resolve times, and want pip to “work better”. There’s a common issue that people don’t really know how the resolver works, and in particular don’t appreciate why the problem is hard, so they tend to get frustrated when we can’t “just solve the issue”.

Describe the solution you’d like A high-level description in the documentation (probably under “topics”) of the problems the resolver faces, the unique issues that make dependency resolution for Python packages hard, and most importantly, the process we go through to find a solution.

The document doesn’t need to cover everything, and absolutely shouldn’t be positioned as the definitive spec, because we need to be able to change the implementation without being held to implied behaviour guarantees.

Alternative Solutions

• Fix the resolver so it works perfectly for everyone. I wish 🙂
• Keep explaining on the tracker when people raise problems. This doesn’t scale, and drains a lot of energy and resource from the core devs. Even for productive and helpful interactions like #10201.

Additional context

• Most of the actual logic comes from resolvelib, so we’ll be (at least in part) documenting what resolvelib does.
• Do we need to tackle the point that the “old resolver” didn’t have the performance issues the new one does?
• Do we need to explicitly state that “must not install conflicting packages” is fundamental?
• Do we need to discuss how the resolver interacts with packages that are already installed? I don’t want to get into --upgrade-strategy, TBH. So let’s not.
• What about “escape hatches” like --no-deps and --ignore-installed? Again, I’m inclined to ignore these.

[pfmoore]

Assigned to myself because I’d like to take a stab at this. But my time is limited. If anyone else is interested and I’ve done nothing about it for a while, feel free to ping me and ask if you can take over.

[pfmoore]

Feel free to hijack that / tack onto the end of it / whatever. 😃

TBH, I’d find it hard to merge the styles, and I don’t feel comfortable just deleting what’s there. So I’ll add my stuff and let someone merge the two later if they want to.