document scalafixOnCompileConfig key & scalafixOnCompile shortcomings

docs/users/installation.md

@@ -155,7 +155,8 @@ Great! You are all set to use Scalafix with sbt :)
 | `scalafixCaching` | `SettingKey[Boolean]`  | Controls whether 2 successive invocations of the `scalafix` `InputTask` with the same arguments & configuration should be incremental. Defaults to `true` if `scalafixOnCompile := true`, `false` otherwise. When enabled, use the `--no-cache` argument to force an exhaustive run.
 | `scalafixConfig` | `SettingKey[Option[File]]` | `.scalafix.conf` file to specify which scalafix rules should run, together with their potential options. Defaults to `.scalafix.conf` in the root directory, if it exists.
 | `scalafixDependencies` | `SettingKey[Seq[ModuleID]]` | Dependencies making [custom rules](#run-custom-rules) available via their simple name. Must be set in `ThisBuild`. Defaults to `Nil`.
-| `scalafixOnCompile` | `SettingKey[Boolean]` | When `true`, Scalafix rule(s) declared in `scalafixConfig` are run on compilation, applying rewrites and failing on lint errors. Defaults to `false`.
+| `scalafixOnCompile` | `SettingKey[Boolean]` | When `true`, Scalafix rule(s) declared in `scalafixConfig` (or `scalafixOnCompileConfig` when set) are run on compilation, applying rewrites and failing on lint errors. Defaults to `false`.
+| `scalafixOnCompileConfig` | `SettingKey[File]` | When this is set and `scalafixOnCompile := true`, the rules and settings from this .scalafix.conf file will be used when Scalafix runs automatically after compilation.
 | `scalafixResolvers` | `SettingKey[Seq[Repository]]` | Custom resolvers where `scalafixDependencies` are resolved from. Must be set in `ThisBuild`. Defaults to: Ivy2 local, Maven Central, Sonatype releases & Sonatype snapshots.
 | `scalafixScalaBinaryVersion` | `SettingKey[String]` | Scala binary version used for Scalafix execution. Defaults to 2.12. For advanced rules such as ExplicitResultTypes to work, it must match the binary version defined in the build for compiling sources. Note that `scalafixDependencies` artifacts must be published against that Scala version.
 
@@ -190,6 +191,40 @@ Both the `scalafix` & the `scalafixAll` task aggregate like the `compile`
 and `test` tasks. To run Scalafix on all projects for both main and test
 sources you can execute `scalafixAll`.
 
+### Run Scalafix automatically on compile
+
+If you set `scalafixOnCompile` to `true`, the rules declared in `.scalafix.conf`
+(or in the file located by `scalafixConfig`) will run automatically each time
+`compile` is invoked either explicitly or implicitly (for example when
+executing `test` or `publishLocal`). Lint errors will fail that invocation,
+while rewrites will be applied.
+
+Although this looks like an easy way to use Scalafix as a linter, use this
+feature with care as it has several shortcomings, for example:
+
+1. Some rules such as `RemoveUnused` can be counter-productive if applied too
+   often/early, as the work-in-progress code that was just added might disappear
+   after a simple `test`.
+1. If you run many semantic rules by default, the last one(s) to run might see
+   stale information and fail the invocation, which needs to be re-run manually.
+   This is [not specific to `scalafixOnCompile`](https://github.com/scalacenter/scalafix/issues/1204),
+   but the problem becomes much more visible with it.
+1. To keep the overhad minimal, `scalafixCaching` is automatically enabled when
+   `scalafixOnCompile` is, which can cause unexpected behaviors if you run into
+   false positive cache hits. `scalafixCaching` can explicitly be set to
+   `false` in that case.
+1. Non-idempotent rewrite rules might get you in an infinite loop where sources
+   never converge - not specific to `scalafixOnCompile` either, but rather
+   confusing when triggered automatically.
+1. Bugs in rule implementations can prevent you from getting a successul
+   `compile`, blocking testing or publishing for example
+
+Some of these shortcomings can be mitigated by the `scalafixOnCompileConfig`
+setting key, which allows to use a separate configuration file whenever
+Scalafix is triggered by `compile`. This way, Scalafix can execute a
+different, safer set of rules compared to the regular `scalafixConfig` that
+remains used for explicit `scalafix` & `scalafixAll` invocations.
+
 ### Enforce in CI
 
 To automatically enforce that Scalafix has been run on all sources, use