From f7f222f28e929dda69e4f5b1d660fc51a133fe09 Mon Sep 17 00:00:00 2001
From: Eric Hanson <5846501+ericphanson@users.noreply.github.com>
Date: Sat, 2 Dec 2023 17:40:05 +0100
Subject: [PATCH] Suggest using `compat` to choose versions of packages (#3704)

---
 docs/src/managing-packages.md | 25 +++++++++++++++++++++++--
 src/API.jl                    |  1 +
 2 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/docs/src/managing-packages.md b/docs/src/managing-packages.md
index fb172c4738..02bdbded67 100644
--- a/docs/src/managing-packages.md
+++ b/docs/src/managing-packages.md
@@ -40,7 +40,7 @@ It is possible to add multiple packages in one command as `pkg> add A B C`.
 The status output contains the packages you have added yourself, in this case, `JSON`:
 
 ```julia-repl
-(@v1.8) pkg> st
+(@v1.11) pkg> st
     Status `~/.julia/environments/v1.8/Project.toml`
   [682c06a0] JSON v0.21.3
 ```
@@ -48,7 +48,7 @@ The status output contains the packages you have added yourself, in this case, `
 The manifest status shows all the packages in the environment, including recursive dependencies:
 
 ```julia-repl
-(@v1.8) pkg> st -m
+(@v1.11) pkg> st -m
 Status `~/environments/v1.9/Manifest.toml`
   [682c06a0] JSON v0.21.3
   [69de0a69] Parsers v2.4.0
@@ -60,6 +60,27 @@ Status `~/environments/v1.9/Manifest.toml`
 
 Since standard libraries (e.g. ` Dates`) are shipped with Julia, they do not have a version.
 
+To specify that you want a particular version (or set of versions) of a package, use the `compat` command. For example,
+to require any patch release of the v0.21 series of JSON after v0.21.4, call `compat JSON 0.21.4`:
+
+```julia-repl
+(@1.11) pkg> compat JSON 0.21.4
+      Compat entry set:
+  JSON = "0.21.4"
+     Resolve checking for compliance with the new compat rules...
+       Error empty intersection between JSON@0.21.3 and project compatibility 0.21.4 - 0.21
+  Suggestion Call `update` to attempt to meet the compatibility requirements.
+
+(@1.11) pkg> update
+    Updating registry at `~/.julia/registries/General.toml`
+    Updating `~/.julia/environments/1.11/Project.toml`
+  [682c06a0] ↑ JSON v0.21.3 ⇒ v0.21.4
+    Updating `~/.julia/environments/1.11/Manifest.toml`
+  [682c06a0] ↑ JSON v0.21.3 ⇒ v0.21.4
+```
+
+See the section on [Compatibility](@ref) for more on using the compat system.
+
 After a package is added to the project, it can be loaded in Julia:
 
 ```julia-repl
diff --git a/src/API.jl b/src/API.jl
index 89b7e6d318..02741d1eb2 100644
--- a/src/API.jl
+++ b/src/API.jl
@@ -2103,6 +2103,7 @@ function compat(ctx::Context, pkg::String, compat_str::Union{Nothing,String}; io
         catch e
             if e isa ResolverError
                 printpkgstyle(io, :Error, string(e.msg), color = Base.warn_color())
+                printpkgstyle(io, :Suggestion, "Call `update` to attempt to meet the compatibility requirements.", color = Base.info_color())
             else
                 rethrow()
             end