Better prerelease docs

[jonasfj]

I couldn't understand what the thing it said before meant.

Then I saw that I wrote it 5 years ago 🙈 🙈 🙈
Then I saw that the PR was edited twice #1785 🤣 🤣 🤣

So what was:

In certain scenarios with nested dependencies the dependency resolution
algorithm in pub, may pick a pre-release over a stable release.

Became:

Sometimes pub might choose a pre-release instead of a stable release;
this can occur when dependencies are nested.

and eventually what landed was:

If a stable package in the dependency graph depends on a pre-release,
then pub chooses that pre-release instead of a stable release.

There is some discussion of the issue here: #1785 (comment)

I suppose we could also say:

If a stable package in the dependency graph depends on a pre-release,
then pub may choose a pre-release even if a stable release is possible.

Which is closer to what it already said, but I'm not sure we want to assuming anyone knows what a "stable package" is, I certainly don't. It's probably a package that has a stable release, but it feels a bit wild just introduce new terms like that with a formal definition.

Also it's nice to have:

• The reasoning: "the version solver does not attempt all solutions"
• The intuition "pub prefers stable releases the same way it prefers newer versions"
• The practical effect: "this rarely happens in practice"

Feel free to use other words, this is really a corner case.

[dart-github-bot]

Visit the preview URL for this PR (updated for commit 2748f6d):

https://dart-dev--pr5808-jonasfj-patch-4-qxo7z590.web.app

[sigurdm]

Perhaps we could expand to something like:

Suggested change

	While `pub` prefers stable releases the same way it prefers newer versions,
	the version solver does not attempt all solutions and may pick a prerelease,
	even when a resolution that doesn't use prelreases exists.
	While `pub` prefers stable releases the same way it prefers newer versions,
	the version solver is applying its heuristics greedily, and stops at the first solution it finds. Thus it might end up stuck at a local maximum, with a solution including prereleases even though a solution without those exists.

[jonasfj]

We could do that, I wouldn't mind -- but it does get rather technical.

Personally, I prefer the shorter less technical thing I wrote. But I don't really care, I just want the nonsense that was there before to go away, and replace it with something that is at-least somewhat sensible.

Even if it's not perfect, it's better than what didn't make sense :D