Reconcile and consolidate type issue troubleshooting pages

[MaryaBelanger]

Fixing type promotion failures (non-promotion-reasons) and Fixing common type problems (sound-problems)

In terms of purpose and subject matter, I can't really tell if they're trying to address different topics. Seems like basically the same thing to me. Does anyone know what the goal was for each page originally?

@sfshaza2 you have a lot of commits early on for Fixing common type problems, any insight?

It seems like Fixing type promotion failures might've been created separately because of how it interacts with analyzer tooling, is that accurate @stereotype441 or @bwilkerson (you both left feedback on the first commit)

Just trying to understand the goal of each so I know what information to put where going forward, thanks!

---

Notes:

• I think /sound-problems could move to live under/alongside "The Dart type system" page
• and /non-promotion could be coupled with "Understanding null safety"

[parlough]

I believe the context is that Fixing common type problems was introduced alongside an optional strong mode (found first in the web Dart dev compiler(DDC)) and then later for Dart 2's sound type system, whereas Fixing type promotion failures was introduced alongside null safety where that class of type problem became much more common than before, so the compiler frontend and analyzer could potentially link to those as a guide for fixing them.

It seems Fixing type promotion failures is just focused on that specific subset of type problems, where one type is not promoted to the expected type automatically and how to potentially fix them.

In the end the goals seem the same like you said, with the added use of tooling linking to Fixing type promotion failures. The style and content of Fixing type promotion failures matches much better with the current site and for using as potential link destinations, so perhaps it would be better to combine them, following that newer style? There are also issues for covering other types of sound issues (#562).

[stereotype441]

It seems like Fixing type promotion failures might've been created separately because of how it interacts with analyzer tooling, is that accurate @stereotype441 or @bwilkerson (you both left feedback on the first commit)

That sounds accurate to me. I agree with @parlough that it would make sense to combine them.

[bwilkerson]

I don't remember the origins of those pages.

I guess the question is what information are we trying to make available and how best to do so. Both pages appear to have the same goal, which is to explain some of the common pitfalls that developers can run into related to the type system. If that's true, then having that information in a single place seems reasonable.

We should also look for opportunities to link to this information from https://dart.dev/tools/diagnostic-messages.

[MaryaBelanger]

Ok, action item will be to consolidate the pages (sound-problems and non-promotion-reasons).

Currently, Fixing type promotion failures doesn't show up anywhere in the left nav. Since it's the more modern page, that should probably be the more visible page.

One thing I like more about sound-problems is that the actual error messages are included with the examples. This would be a good thing to

1. add to the non-promotion-reasons examples, and
2. link to the diagnostic-messages examples

---

More of a stretch (for me, based on my current level of understanding) is identifying relations to diagnostic-messages. A quick skim of diagnostic-messages, it seems that there aren't type promotion failure specific messages on that page (?), but definitely type problems in general.

Which of those diagnostic messages correlate to type promotion failures?
undefined_getter and undefined_method are on diagnostic-messages and sound-problems, but sound-problems seems like it's giving a specific type-related example while the actual diagnostic message is probably applied more generally. Like, undefined_getter and undefined_method are not necessarily always about type, and when they are about type, they're not specifically about type promo failure. More nuance there for me to look into, but will definitely link to diagnostic-messages as a reference wherever possible.

[stereotype441]

Which of those diagnostic messages correlate to type promotion failures?

Good question. In principle a lot of errors could result from a type promotion failure, but I would guess the most common ones are probably undefined_getter, undefined_method, invalid_assignment, argument_type_not_assignable, and unchecked_use_of_nullable_value.

[bwilkerson]

... will definitely link to diagnostic-messages as a reference wherever possible.

I was actually thinking about links in the opposite direction. If a diagnostic could be the result of a type promotion failure the docs should probably say so and have a link back to the more complete description of what can cause promotion failures. (Though in the IDE there will often already be a direct link to this documentation. Which means that we'll need to be careful not to break those links.)