Add FAQ on imports

[mtomko]

This is to address the potential confusion with java.lang.IO

I did experiment with a third option:

import java.lang.IO as _

object Test {

  def test: IO[Unit] = ???

}

but empirically, this didn't actually work - for some reason scalac insisted that the problem was not a missing type but rather than IO doesn't take type parameters (implying that it was referring to java.lang.IO rather than cats.effect.IO. I think that's odd but it's more likely that the right solution is just to import cats.effect.IO directly anyway.

[durban]

Another option is a proper -release < 25 (or -java-output-version on dotty) scalac option. Of course, that's not applicable if one needs something from JDK 25.

[mtomko]

I'll note those options too. I don't know how long on the tooth we want to get for this potentially niche issue, though - presumably for the most part this will be useful only to beginners, as a seasoned Scala dev will recognize right away that the problem must be a conflicting definition.

[durban]

Sure, I've just wanted to mention it.

[mtomko]

I spent a little time thinking about this and decided that unless people feel strongly that this workaround bears mentioning, it makes the answer take up a lot of space for a topic that's really just a minor gotcha. I also wondered if this question/answer should maybe go below the Scala CLI one (currently directly below it).

My rationale is that anyone who knows the JVM well enough to have preferences about which JDK or JVM they use versus which they target, is going to solve a confusing message from the IDE by explicitly importing the data type. For me the critical issue is that java.lang.IO confuses the auto-import behavior of the the IDE (at least, it does for Metals) - the "IO takes no parameters" error prevents Metals from suggesting that we could import the IO type. Maybe there's a way to fix this in Metals in the long term.

[djspiewak]

@mtomko I defer to you, but I think it's a reasonable FAQ entry. Helps the LLMs anyway.