From 3c28c5ecf1cac63a3c38839ce106d3efb62d866a Mon Sep 17 00:00:00 2001
From: JamesWrigley <james@puiterwijk.org>
Date: Sun, 1 Dec 2024 13:20:04 +0100
Subject: [PATCH] fixup! Document how to support different distributed worker
 backends

---
 docs/src/support-preferences.md | 46 +++++++++++++++++++++------------
 1 file changed, 30 insertions(+), 16 deletions(-)

diff --git a/docs/src/support-preferences.md b/docs/src/support-preferences.md
index 891d04d..63f7212 100644
--- a/docs/src/support-preferences.md
+++ b/docs/src/support-preferences.md
@@ -7,29 +7,43 @@ that they are not compatible at all. E.g. you cannot
 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:
+choose which package to load.
+
+Here's an example for a package named Foo.jl:
 ```julia
-import Preferences: load_preference
+module Foo
+
+import Dependency
+import Preferences: @load_preference, @set_preferences!
 
-const distributed_library_name = load_preference("distributed-library", "name")
-if distributed_library_name == "DistributedNext"
+const distributed_package = @load_preference("distributed-package")
+if distributed_package == "DistributedNext"
     using DistributedNext
-elseif distributed_library_name == "Distributed"
+elseif distributed_package == "Distributed"
     using Distributed
 else
-    error("Unsupported `distributed-library`: '$(distributed_library_name)'")
+    error("Unsupported `distributed-package`: '$(distributed_package)'")
 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_distributed_package!(value[="Distributed|DistributedNext"])
 
-set_preferences!("distributed-library", "name" => "DistributedNext")
+Set a [preference](https://github.com/JuliaPackaging/Preferences.jl) for using
+either the Distributed.jl stdlib or DistributedNext.jl. You will need to restart
+Julia after setting a new preference.
+"""
+function set_distributed_package!(value)
+    # Set preferences for all dependencies
+    Dependency.set_distributed_package!(value)
+
+    @set_preferences!("distributed-package" => value)
+    @info "Foo.jl preference has been set, restart your Julia session for this change to take effect!"
+end
+
+end
 ```
 
-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.
+Users will then be able to call
+e.g. `Foo.set_distributed_package!("DistributedNext")`. Note that
+`Foo.set_distributed_package!()` should also set the preferences of any dependencies
+of Foo.jl that use a distributed worker package.