Explain why to use -target -release etc

[som-snytt]

reproduction steps

It comes up all the time. Is there a plugin I can use to automate my expectations? sbt-seth?

https://discord.com/channels/632150470000902164/632150470000902166/938864015545880626

problem

https://docs.scala-lang.org/overviews/jdk-compatibility/overview.html should probably explain option selection.

[SethTisue]

really good doc on this would note the Scala 2 vs 3 differences on these flags, too

it came up just the other day in some comment @smarter made over the in the Dotty repo, but I wasn't able to find it just now when I searched. (it was something like "Scala 2 should be changed to match the Scala 3 behavior")

Plus the absence of this is exacerbated by #1711 😕

[Jasper-M]

There you go https://contributors.scala-lang.org/t/improving-scala-3-forward-compatibility/5298/13?u=jasper-m

[mrdziuban]

This may go beyond the scope of documentation changes, but I was also thrown off that each option needed to be set differently in my build.sbt -- -release needs to be followed by a space then the version, while -target needs a colon then the version

// correct
scalacOptions ++= Seq("-release", "17", "-target:17")
// incorrect -- "'-release' does not accept multiple arguments"
scalacOptions ++= Seq("-release:17", "-target:17")
// incorrect -- "Usage: -target:<target> where <target> choices are 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18 (default: 8)"
scalacOptions ++= Seq("-release", "17", "-target", "17")

[SethTisue]

Everyone should keep piling on with bits of info for the eventual doc addition! 👍

[som-snytt]

@mrdziuban that is fixed by a recent PR so that colon is handled but if absent it takes the next arg.

[dalbani]

For the record:

@mrdziuban that is fixed by a recent PR so that colon is handled but if absent it takes the next arg.

Looks like it was scala/scala#9982.