docs: Add a warning about dart-lang/sdk#43763 to sortedBy

[eseidel]

dart-lang/sdk#43763 is supposedly hard to fix in the language, but is a common gotcha
when dealing with sortedBy, so the least we can do is at least alert users and tell them
how to work around it.

Fixes #271.

---

• I’ve reviewed the contributor guide and applied the relevant portions to this PR.

Contribution guidelines:

• See our contributor guide for general expectations for PRs.
• Larger or significant changes should be discussed in an issue before creating a PR.
• Contributions to our repos should follow the Dart style guide and use dart format.
• Most changes should add an entry to the changelog and may need to rev the pubspec package version.
• Changes to packages require corresponding tests.

Note that many Dart repos have a weekly cadence for reviewing PRs - please allow for some latency before initial review feedback.

[eseidel]

What it looks like:

[devoncarew]

Thanks for the contribution! Can you add an entry in the changelog for this?

@natebosch or @lrhn - can you review?

[natebosch]

I would prefer if this was handled in a more centralized way. dart-lang/sdk#43763 (comment)

If we can't accomplish this in the analyzer we could work on the phrasing here.

[eseidel]

I'm not at all wedded to this solution. Just witnessed myself and two other colleagues each independently (!) hit this error in the last few months and so went to document where it might be seen by others. I wasn't aware of dart-lang/sdk#43763 until this morning (and managed to fumble my way to a solution in my code without finding it), but after reading dart-lang/sdk#43763 and seeing it's supposedly a 10 year old issue with no easy fix, felt like documenting the failure to avoid others being confused by it could at least help. 🤷