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)?
docs/users/cross-compilation.md
Outdated
| 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.
docs/users/cross-compilation.md
Outdated
| * 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.
docs/users/cross-compilation.md
Outdated
| * 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
docs/users/cross-compilation.md
Outdated
| ### 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
docs/users/cross-compilation.md
Outdated
|
|
||
| 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 |
docs/users/cross-compilation.md
Outdated
| ├── project/ | ||
| │ └── build config… |
There was a problem hiding this comment.
Irrelevant? also, build.sbt is at the root
|
Thanks for the thorough review! I’ve applied all requested changes: Verified locally with 
|
|
@arnavsharma990 did you forget to push? |
- Rename file to cross-building.md for URL consistency - Replace 'cross-compilation' with 'cross-building' throughout - Remove speculative/future-looking sections - Add Limitations section explaining no conditional config support - Clarify that scalac/semanticdb flags belong in build tool - Update CLI examples to use defaults from config file - Add sidebar entry under Usage section - Update translations in en.json
arnavsharma990
force-pushed
the
issue-1747-docs-cross-compilation
branch
from
bf4a709 to
42fe994
Compare
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive documentation for using Scalafix in cross-compiled Scala 2 and Scala 3 projects, addressing issue #1747. It introduces best practices for managing version-specific configurations.
- Explains why separate configuration files are needed for different Scala versions
- Provides concrete examples of file layouts using HOCON's
includepattern - Shows how to wire version-specific configs in sbt, CLI, and CI environments
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| website/sidebars.json | Adds "cross-building" entry to the Usage section navigation |
| website/i18n/en.json | Adds internationalization title entry for the new cross-building page |
| docs/users/cross-building.md | New comprehensive guide covering configuration splitting, file organization, sbt setup, CLI usage, and recommendations for cross-compiled projects |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
@bjaglin Sorry, I somehow forgot to push earlier , I’ve pushed the updates now. PTAL |
Co-authored-by: Brice Jaglin <[email protected]>
Updated documentation on cross-building setups to clarify Scalafix usage across Scala versions. Adjusted file naming conventions and provided clearer examples for configuration.
|
@bjaglin I’ve addressed all the review feedback, updated the introduction for clarity, flattened the Scalafix config layout to root-level files, aligned all examples and references, and removed the recommendations section as suggested. Thanks for the detailed review. |
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.