From 7ed5b4f3215690c58d0ffe2d0251cd22d6848ddb Mon Sep 17 00:00:00 2001
From: Meriam Lachkar <meriam.lachkar@gmail.com>
Date: Mon, 14 Sep 2020 15:33:46 +0200
Subject: [PATCH] Add documentation to cross publish rules

---
 docs/developers/cross-publish-custom-rules.md | 41 +++++++++++++++++++
 docs/developers/tutorial.md                   |  3 +-
 website/sidebars.json                         |  3 +-
 3 files changed, 45 insertions(+), 2 deletions(-)
 create mode 100644 docs/developers/cross-publish-custom-rules.md

diff --git a/docs/developers/cross-publish-custom-rules.md b/docs/developers/cross-publish-custom-rules.md
new file mode 100644
index 000000000..9fa0a72d4
--- /dev/null
+++ b/docs/developers/cross-publish-custom-rules.md
@@ -0,0 +1,41 @@
+---
+id: cross-publish-custom-rules
+title: Cross publish custom rules
+---
+## Already existing custom rules
+If your rule is meant only for one scala version, for example, a rule that
+automates a migration from one scala version to another, you don't need
+to cross publish your rule. In fact, your rule should only be run for
+this specific scala version, and should only be published in this
+scala version.
+
+Otherwise, if your rule is not specific to a scala version, and in order
+to make the migration to scalafix v1 smooth for users, we need the rules
+authors to cross-publish their rules for the scala versions they support.
+For most rules, this change requires only modifying the build settings as follows:
+
+```diff
+ // build.sbt
+ scalaVersion := V.scala212,
++crossScalaVersions := List(V.scala213, V.scala212, V.scala211),
+```
+The second step is to update your CI to run tests on the different
+scala versions your rule is being cross-published to. For that, you only
+need prefix the test action with `+`. For example:
+```
+sbt +test
+```
+
+## New rules
+The scalafix template has already been updated to automatically
+cross publish rules (see [pull request](https://github.com/scalacenter/scalafix/issues/1202)).
+Therefore, no change is required if you are writing a new rule.
+
+
+
+## Projects that already cross-publish
+[Edit](https://github.com/scalacenter/scalafix/edit/master/docs/developers/cross-publish-custom-rules.md) this page to submit a pull request that adds more project that cross-publish their rule.
+This is a non-exhaustive list of pull request that have cross-published their rules:
+- [liancheng/**scalafix-organize-imports**](https://github.com/liancheng/scalafix-organize-imports/pull/69)
+- [scala/**scala-rewrites**](https://github.com/scala/scala-rewrites/pull/33)
+- [NeQuissimus/**sort-imports**](https://github.com/NeQuissimus/sort-imports/pull/66)
diff --git a/docs/developers/tutorial.md b/docs/developers/tutorial.md
index ebd5b1be9..f211a1b9c 100644
--- a/docs/developers/tutorial.md
+++ b/docs/developers/tutorial.md
@@ -643,7 +643,8 @@ The expansion rules for `github:org/repo` are the following:
 
 > If your rule only targets a single codebase and is not meant to be
 > distributed, you might want to develop it [as part of your existing
-> build](local-rules.md) instead.
+> build](local-rules.md) instead. You may also read [how to cross publish you rules](cross-publish-custom-rules.md)
+> once you have set up the necessary configuration to publish to Maven Central.
 
 Run the following sbt command to publish a rule locally.
 
diff --git a/website/sidebars.json b/website/sidebars.json
index 760d3b5a6..a27319f3e 100644
--- a/website/sidebars.json
+++ b/website/sidebars.json
@@ -19,7 +19,8 @@
       "developers/setup",
       "developers/before-you-begin",
       "developers/tutorial",
-      "developers/local-rules"
+      "developers/local-rules",
+      "developers/cross-publish-custom-rules"
     ],
     "API Reference": [
       "developers/api",