Document how to support different distributed worker backends

Author: JamesWrigley

docs/make.jl

@@ -34,6 +34,7 @@ makedocs(;
          sitename = "DistributedNext",
          pages = [
              "DistributedNext" => "index.md",
+             "support-preferences.md",
              "changelog.md"
          ],
          warnonly = [:missing_docs, :cross_references],

docs/src/support-preferences.md

@@ -0,0 +1,35 @@
+# Supporting both Distributed and DistributedNext
+
+The [Distributed.jl](https://docs.julialang.org/en/v1/stdlib/Distributed/)
+standard library and DistributedNext are independent Julia modules, which means
+that they are not compatible at all. E.g. you cannot
+`DistributedNext.remotecall()` a worker added with `Distributed.addprocs()`. If
+you as a package developer want to make your package support both Distributed
+and DistributedNext, we suggest using
+[Preferences.jl](https://juliapackaging.github.io/Preferences.jl/stable/) to
+choose which library to load:
+```julia
+import Preferences: load_preference
+
+const distributed_library_name = load_preference("distributed-library", "name")
+if distributed_library_name == "DistributedNext"
+    using DistributedNext
+elseif distributed_library_name == "Distributed"
+    using Distributed
+else
+    error("Unsupported `distributed-library`: '$(distributed_library_name)'")
+end
+```
+
+`distributed-library` is a top-level name that we recommend all packages who
+want to support switching backends use. The advantage of using a global
+preference instead of a per-package preference is that you can set it once:
+```julia
+import Preferences: set_preferences!
+
+set_preferences!("distributed-library", "name" => "DistributedNext")
+```
+
+And all packages that support the `distributed-library` preference will pick
+that up automatically so an end-user doesn't need to worry about setting
+preferences for all of the dependencies of the package that they want to use.