Issue 1747 docs cross compilation #2323
Conversation
|
CI is no really needed, since this is just a doc, but it might take a while before we review in detail though. |
|
okay got it |
bjaglin
left a comment
bjaglin
left a comment
There was a problem hiding this comment.
Thanks for taking the time to write that down, docs are very important! Have a look at my suggestions, I think the doc could be a bit more concise.
Also, I think the amount of people using the CLI is very low, so I wonder if we couldn't just make a paragraph explaining the sbt setup in the main page (which is sbt-centric)?
| Scala 3 compilation unit is processed, and vice versa. Until Scalafix grows | ||
| conditional configuration, the safest way to avoid those failures is to split |
There was a problem hiding this comment.
There is no plan to do conditional configuration so the "Until" can be misleading. IMHO, documentation should be about what's available.
| * Scala 2 only flags such as `-Ywarn-unused-import` or SemanticDB options using | ||
| `-P:semanticdb` are rejected by Scala 3. |
There was a problem hiding this comment.
How is that impacting the configuration file? That looks like a build tool concern to me.
| * Isolate risky scalac options (`-Wunused`, `-Ywarn-unused-import`, `-P:semanticdb`) | ||
| inside each version-specific file or sbt setting. |
There was a problem hiding this comment.
Same comment as above - scalac-options are not part of the config so I don't understand that part
| ### Looking ahead | ||
|
|
||
| Issue [#1747](https://github.com/scalacenter/scalafix/issues/1747) tracks better | ||
| ergonomics for cross compilation. Potential improvements include: | ||
|
|
||
| * Conditional configuration blocks directly inside `.scalafix.conf` (for example | ||
| `if scalaVersion.startsWith("3.")`). | ||
| * First-class support for including multiple files via CLI flags. | ||
| * Allowing rule selection based on the detected input Scala dialect. | ||
|
|
||
| Until those land, the include-based layout above is the recommended, battle-tested | ||
| approach. | ||
|
|
There was a problem hiding this comment.
I don't think we should advertize potential improvements in the docs, as it's unclear if there is a need for it, especially as 2.x is on its way out and scalafix is kept updated but no-one is actively adding features to it. As a matter of fact, I was hoping to close #1747 with this doc update.
| ``` | ||
| ### Multiple values for CLI flags |
There was a problem hiding this comment.
this is merged, you can rebase against main
| @@ -0,0 +1,144 @@ | |||
| --- | |||
| id: cross-compilation | |||
There was a problem hiding this comment.
we should reference that from the side bar
scalafix/website/sidebars.json
Line 3 in 831c146
| HOCON syntax supports nested includes, so feel free to create the hierarchy that | ||
| matches your team conventions. | ||
|
|
||
| ## Selecting the right config in sbt |
There was a problem hiding this comment.
shouldn't sbt and CLI be at the same header level?
|
|
||
| rules += RemoveUnused | ||
|
|
||
| // Scala 2 only compilers flags or rule settings |
There was a problem hiding this comment.
As mentioned elsewhere, we should focus on compatibility (it's not necessarily about compiler flags but it can be new language features - although that's mostly for community rules, that you don't mention)
| // Scala 2 only compilers flags or rule settings | |
| // Scala 2 only rules or rule settings |
| ├── project/ | ||
| │ └── build config… |
There was a problem hiding this comment.
Irrelevant? also, build.sbt is at the root
| title: Cross compilation setups | ||
| --- | ||
|
|
||
| Cross-building the same codebase with Scala 2.13 and Scala 3.3+ is common, but |
There was a problem hiding this comment.
I have a personal preference for cross-building rather than cross-compilation as it puts less emphasis on the compile phase - let's just make sure we use the same term in the header and the body
|
Thanks for the thorough review! I’ve applied all requested changes: Verified locally with 
|
3 participants
Fixes #1747
This PR adds a new documentation page explaining best practices for using
Scalafix in cross-compiled Scala 2 and Scala 3 projects.
It covers:
base.confplus per-version overridesThis is a documentation-only update.