Issue 1747 docs cross compilation #2323

arnavsharma990 · 2025-11-26T14:35:57Z

This PR adds a new documentation page explaining best practices for using
Scalafix in cross-compiled Scala 2 and Scala 3 projects.

It covers:

Why Scalafix config fails across different Scala versions
How to structure a shared base.conf plus per-version overrides
Using the “include” pattern for shared configuration
SBT configuration to automatically pick the correct config file
CLI/CI examples for selecting per-version configs
Ideas for future improvements (conditional config, include support, etc.)

This is a documentation-only update.

arnavsharma990 · 2025-11-26T14:37:32Z

Could someone please approve the workflow run so CI can start?

@tgodzik @ckipp01

tgodzik · 2025-11-26T14:55:26Z

CI is no really needed, since this is just a doc, but it might take a while before we review in detail though.

arnavsharma990 · 2025-11-26T14:57:54Z

okay got it

bjaglin

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)?

bjaglin · 2025-11-27T20:43:19Z

docs/users/cross-compilation.md

+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 is no plan to do conditional configuration so the "Until" can be misleading. IMHO, documentation should be about what's available.

bjaglin · 2025-11-27T20:45:44Z

docs/users/cross-compilation.md

+* Scala 2 only flags such as `-Ywarn-unused-import` or SemanticDB options using
+  `-P:semanticdb` are rejected by Scala 3.


How is that impacting the configuration file? That looks like a build tool concern to me.

bjaglin · 2025-11-27T20:49:13Z

docs/users/cross-compilation.md

+* Isolate risky scalac options (`-Wunused`, `-Ywarn-unused-import`, `-P:semanticdb`)
+  inside each version-specific file or sbt setting.


Same comment as above - scalac-options are not part of the config so I don't understand that part

bjaglin · 2025-11-27T20:51:18Z

docs/users/cross-compilation.md

+### 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.
+


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.

bjaglin · 2025-11-27T20:51:37Z

docs/users/installation.md


 ```

+### Multiple values for CLI flags


this is merged, you can rebase against main

docs/users/cross-compilation.md

docs/users/cross-building.md

bjaglin · 2025-11-27T21:01:05Z

docs/users/cross-compilation.md

+
+rules += RemoveUnused
+
+// Scala 2 only compilers flags or rule settings


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)

Suggested change

// Scala 2 only compilers flags or rule settings

// Scala 2 only rules or rule settings

bjaglin · 2025-11-27T21:02:27Z

docs/users/cross-compilation.md

+├── project/
+│   └── build config…


Irrelevant? also, build.sbt is at the root

docs/users/cross-building.md

arnavsharma990 · 2025-11-28T09:17:34Z

Thanks for the thorough review! I’ve applied all requested changes:
– Consistent use of “cross-building”
– Removed speculative/future language
– Added a Limitations section
– Clarified build-tool vs config responsibilities
– Updated CLI examples to use defaults
– Sidebar added
– Renamed file to cross-building.md and updated translations

Verified locally with sbt ci-docs and yarn start.
Everything renders correctly. PTAL!

bjaglin · 2025-12-10T10:46:12Z

@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

Copilot

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 include pattern
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.

arnavsharma990 · 2025-12-10T11:23:28Z

@bjaglin Sorry, I somehow forgot to push earlier , I’ve pushed the updates now. PTAL

bjaglin · 2025-12-10T11:24:46Z

docs/users/cross-building.md

+## Recommendations
+
+* Keep rules that truly work on both versions inside `common.conf`.
+* Manage scalac and SemanticDB flags inside the build tool per target; Scalafix
+  configs focus solely on rules and rule-specific settings.
+* Document in `README.md` or `CONTRIBUTING.md` which rules run on which Scala
+  version to reduce confusion for new contributors.
+


the first item is already mentioned above and the 2 last are not related to scalafix, so I would simply drop that

Suggested change

## Recommendations

* Keep rules that truly work on both versions inside `common.conf`.

* Manage scalac and SemanticDB flags inside the build tool per target; Scalafix

configs focus solely on rules and rule-specific settings.

* Document in `README.md` or `CONTRIBUTING.md` which rules run on which Scala

version to reduce confusion for new contributors.

bjaglin · 2025-12-10T11:27:09Z

docs/users/cross-building.md

+HOCON syntax supports nested includes, so feel free to create the hierarchy that
+matches your team conventions.
+
+## Selecting the right config in sbt


Suggested change

## Selecting the right config in sbt

## Selecting the right configuration file

### sbt

bjaglin · 2025-12-10T11:30:27Z

docs/users/cross-building.md

+the HOCON `include` syntax. One convenient layout is:
+
+```
+.
+└── scalafix/
+    ├── common.conf
+    ├── scala2.conf
+    └── scala3.conf
+```


In most OSS projects I have seen, files are at the root, where .scalafix.conf is looked up by default - I think adding an extra directory complicates discovery.

https://github.com/search?q=.scalafix-scala3.conf&type=code

What about flatteing the layour here and across the doc?

.scalafix-common.conf

.scalafix-scala2.conf

.scalafix-scala3.conf

bjaglin · 2025-12-10T12:40:27Z

docs/users/cross-building.md

+Cross-building the same codebase with Scala 2.13 and Scala 3.3+ is common, but
+it collides with how Scalafix resolves rules and compiler options. A rule or
+build-tool flag that only works on Scala 2 can crash Scalafix when the Scala 3
+compilation unit is processed, and vice versa. Split your configuration per
+Scala version and let the build tool wire the right file.
+
+## Why separate configs are required today
+
+* Scala 2 only scalac flags such as `-Ywarn-unused-import` or SemanticDB options
+  using `-P:semanticdb` belong in the build tool. Those settings differ per
+  target and cannot be inferred by Scalafix.
+* Some built-in or community rules rely on compiler symbols present only in a
+  single Scala major version.
+* The CLI currently ingests a single `.scalafix.conf`; there is no per-target
+  override like sbt’s `CrossVersion`.
+
+## Limitations
+
+Scalafix cannot conditionally toggle rules or scalac options based on the input
+Scala version. Provide a separate config file per Scala version and have sbt,
+mill, or your CLI invocation choose the right file along with the correct
+compiler flags. See [issue #1747](https://github.com/scalacenter/scalafix/issues/1747)
+for additional background.


I still find this quite hard to follow since it mixes context/rationale, problem and solution space. Here is an attempt at doing this with one paragraph for each:

In a codebase cross-building against several binary versions of Scala, it is advised to run Scalafix several times, for each Scala version. That allows to cover version-specific files and to benefit from compiler diagnostics from several Scala versions for common files.

However, since rules can be specific or only support a subset of features for a given Scala version, a different set of rules or rule features might have to be selected for each run, in order to avoid failing the entire run and preventing relevant rules to run.

Since nothing in the current API allows rules to advertize their limitations programmatically to Scalafix, this page explains how to do it manually.

bjaglin · 2025-12-10T12:42:43Z

docs/users/cross-building.md

+`scala2.conf`
+```scala
+include "common.conf"
+
+rules += RemoveUnused
+
+// Scala 2 only rule settings
+RemoveUnused {
+  imports = true
+}
+```
+
+`scala3.conf`
+```scala
+include "common.conf"
+
+rules += LeakingImplicitClassVal
+
+// Scala 3 specific tweaks go here
+OrganizeImports {
+  groupedImports = Keep
+}
+```


Are these configuration files solving real limitations as described in the intro? AFAIK RemoveUnused.imports is fine with Scala 3 and LeakingImplicitClassVal is not related to Scala 3 (more to Scala 3 actually).

bjaglin reviewed Nov 27, 2025

View reviewed changes

arnavsharma990 force-pushed the issue-1747-docs-cross-compilation branch from bf4a709 to 42fe994 Compare December 10, 2025 11:19

Copilot AI review requested due to automatic review settings December 10, 2025 11:19

Copilot started reviewing on behalf of arnavsharma990 December 10, 2025 11:19 View session

Copilot AI reviewed Dec 10, 2025

View reviewed changes

bjaglin reviewed Dec 10, 2025

View reviewed changes

		Scala 3 compilation unit is processed, and vice versa. Until Scalafix grows
		conditional configuration, the safest way to avoid those failures is to split

		* Scala 2 only flags such as `-Ywarn-unused-import` or SemanticDB options using
		`-P:semanticdb` are rejected by Scala 3.

		* Isolate risky scalac options (`-Wunused`, `-Ywarn-unused-import`, `-P:semanticdb`)
		inside each version-specific file or sbt setting.


		rules += RemoveUnused

		// Scala 2 only compilers flags or rule settings

	// Scala 2 only compilers flags or rule settings
	// Scala 2 only rules or rule settings

Issue 1747 docs cross compilation #2323

Are you sure you want to change the base?

Issue 1747 docs cross compilation #2323

Uh oh!

Conversation

arnavsharma990 commented Nov 26, 2025

It covers:

Uh oh!

arnavsharma990 commented Nov 26, 2025

Uh oh!

tgodzik commented Nov 26, 2025

Uh oh!

arnavsharma990 commented Nov 26, 2025

Uh oh!

bjaglin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

arnavsharma990 commented Nov 28, 2025

Uh oh!

bjaglin commented Dec 10, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

arnavsharma990 commented Dec 10, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants