Add example of manually checking specifications

[MilesCranmer]

The Compatibility guide is very helpful, but I still find the exact syntax easy to forget, and find myself repeatedly checking this guide whenever I'm creating a complex version specification.

I recently found the Pkg.Versions.semver_spec as a way to manually parse the version string. I have found this useful for my own work and I thought it would be helpful to give an example of how to use this to explicitly check versions, and make sure you aren't too constrained or too flexible in a given version spec.

I add the following subsection to the docs:

---

Checking specifications

Pkg.jl parses a given version specification using Pkg.Versions.semver_spec.
You can check if a particular version of a package is contained in a particular
range by using this command. For example:

julia> v"0.1.0" in Pkg.Versions.semver_spec("=0.1")
true

julia> v"0.1.0" in Pkg.Versions.semver_spec("=0.1.1")
false

julia> v"0.1.0" in Pkg.Versions.semver_spec("0.1 - 0.2")
true

julia> v"0.3.0" in Pkg.Versions.semver_spec("~0.3.2")
false

julia> v"0.3.3" in Pkg.Versions.semver_spec("0.1 - 0.2, ~0.3.2")
true

julia> # Grid of versions:
       versions = [[VersionNumber(major, minor, patch) for patch=0:8, minor=0:3, major=0:1]...];

julia> filter(v -> v in Pkg.Versions.semver_spec("0.1.8 - 0.2.2, ^0.3.6"), versions)
7-element Vector{VersionNumber}:
 v"0.1.8"
 v"0.2.0"
 v"0.2.1"
 v"0.2.2"
 v"0.3.6"
 v"0.3.7"
 v"0.3.8"

[KristofferC]

I think this is a good idea and we should imo also:

• Give it a docstring.
• Make it public.
• Give it a better name.

[MilesCranmer]

That all sounds good to me.

For naming, maybe just something like parse_compat?

[DilumAluthge]

Does this mean that we have to make Pkg.Versions.VersionSpec part of the public API? Because semver_spec returns a VersionSpec?

[MilesCranmer]

Ping on this, I ran into this again and would have found it useful to have this in the docs

[MilesCranmer]

Is parse_compat a good name? I can add it if that sounds good.

[IanButterworth]

parse_compat sounds good to me 👍

[DilumAluthge]

Just bumping my comment here: #3847 (comment)

Does this mean that we have to make Pkg.Versions.VersionSpec part of the public API? Because semver_spec returns a VersionSpec?

---

It seems like all of the use cases here are for calling x in semver_spec("foo"), right? Not for using the return value of semver_spec("foo") directly? So how about we keep semver_spec("foo") private, and we have a new public function satisfies_compat_entry(x, "foo") = x in semver_spec("foo")? This allows us to avoid needing to make VersionSpec part of the public API.

[DilumAluthge]

We can pick whatever name we want, I just gave satisfies_compat_entry() as an example.

[MilesCranmer]

@DilumAluthge who was your question addressed to? Just want to make sure I didn't miss it

[DilumAluthge]

Just the group as a whole.

[DilumAluthge]

It seems like all of the use cases here are for calling x in semver_spec("foo"), right? Not for using the return value of semver_spec("foo") directly? So how about we keep semver_spec("foo") private, and we have a new public function satisfies_compat_entry(x, "foo") = x in semver_spec("foo")? This allows us to avoid needing to make VersionSpec part of the public API.

Implemented in #4292.

[IanButterworth]

#4292 is on the way to merge so we can close this.