Suggest using `compat` to choose versions of packages

[ericphanson]

I think this should be emphasized as "the" way to get the versions you want. Many times folks fight with the resolver to get it to resolve they way they want, when the declarative approach with compat is better. Therefore I think compat belongs in the basic starting instructions.

[IanButterworth]

You could add a hint to update to the resolver error message too?

[ericphanson]

Yeah, that sounds worthwhile, I will try do so

[ericphanson]

Here is what the hint looks like:

julia> Pkg.API.compat(Pkg.Types.Context(), "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.1 and project compatibility 0.21.4 - 0.21
        Hint Call `update` to attempt to meet the compatibility requirements.

I'm using Pkg.API.compat since I'm not sure how to trigger the repl mode with my second copy of Pkg I've loaded to test it.

[ericphanson]

Test failures seem unrelated

[ Info: Pkg test output is silenced
[134](https://github.com/JuliaLang/Pkg.jl/actions/runs/6982430794/job/19001577845?pr=3704#step:6:135)
Username for 'https://github.com/': Username for 'https://github.com/': fatal: could not read Username for 'https://github.com/': terminal prompts disabled
[135](https://github.com/JuliaLang/Pkg.jl/actions/runs/6982430794/job/19001577845?pr=3704#step:6:136)
fatal: could not read Username for 'https://github.com/': terminal prompts disabled
[136](https://github.com/JuliaLang/Pkg.jl/actions/runs/6982430794/job/19001577845?pr=3704#step:6:137)
testing: Test Failed at /Users/runner/work/Pkg.jl/Pkg.jl/test/pkg.jl:244
[137](https://github.com/JuliaLang/Pkg.jl/actions/runs/6982430794/job/19001577845?pr=3704#step:6:138)
  Expression: any(endswith(".cov"), readdir(pkgdir))
[138](https://github.com/JuliaLang/Pkg.jl/actions/runs/6982430794/job/19001577845?pr=3704#step:6:139)

[139](https://github.com/JuliaLang/Pkg.jl/actions/runs/6982430794/job/19001577845?pr=3704#step:6:140)
Stacktrace:
[140](https://github.com/JuliaLang/Pkg.jl/actions/runs/6982430794/job/19001577845?pr=3704#step:6:141)
 [1] macro expansion
[141](https://github.com/JuliaLang/Pkg.jl/actions/runs/6982430794/job/19001577845?pr=3704#step:6:142)
   @ ~/work/Pkg.jl/Pkg.jl/test/pkg.jl:183 [inlined]
[142](https://github.com/JuliaLang/Pkg.jl/actions/runs/6982430794/job/19001577845?pr=3704#step:6:143)
 [2] macro expansion
[143](https://github.com/JuliaLang/Pkg.jl/actions/runs/6982430794/job/19001577845?pr=3704#step:6:144)
   @ ~/hostedtoolcache/julia/nightly/x64/share/julia/stdlib/v1.11/Test/src/Test.jl:676 [inlined]
[144](https://github.com/JuliaLang/Pkg.jl/actions/runs/6982430794/job/19001577845?pr=3704#step:6:145)
 [3] macro expansion
[145](https://github.com/JuliaLang/Pkg.jl/actions/runs/6982430794/job/19001577845?pr=3704#step:6:146)
   @ ~/work/Pkg.jl/Pkg.jl/test/pkg.jl:183 [inlined]
[146](https://github.com/JuliaLang/Pkg.jl/actions/runs/6982430794/job/19001577845?pr=3704#step:6:147)
 [4] macro expansion
[147](https://github.com/JuliaLang/Pkg.jl/actions/runs/6982430794/job/19001577845?pr=3704#step:6:148)
   @ ~/hostedtoolcache/julia/nightly/x64/share/julia/stdlib/v1.11/Test/src/Test.jl:1598 [inlined]
[148](https://github.com/JuliaLang/Pkg.jl/actions/runs/6982430794/job/19001577845?pr=3704#step:6:149)
 [5] (::Main.PkgTestsOuter.PkgTestsInner.OperationsTest.var"#1#16")(project_path::String)
[149](https://github.com/JuliaLang/Pkg.jl/actions/runs/6982430794/job/19001577845?pr=3704#step:6:150)
   @ Main.PkgTestsOuter.PkgTestsInner.OperationsTest ~/work/Pkg.jl/Pkg.jl/test/pkg.jl:181

Some kind of coverage issue?

[IanButterworth]

Though I'm not sure Hint is the right term. It's a little pedagogical/mystery novel-ish. Perhaps Suggestion?

[ericphanson]

Looks good. I think the docs need updating for the new hint?

Those are run in the 1.8 env matching the existing docs. But 1.8 won't have the hint. Should we update to 1.11?

[IanButterworth]

Should we update to 1.11?

Yeah. New docs should generally be in latest. (We probably should update all docs to latest before new releases.. but that's a fair bit of work)

[ericphanson]

here it is with "suggestion" btw

[ericphanson]

bump