Document version offset numbers

[felixcremer]

According to https://docs.binarybuilder.org/stable/building/#Version-number the version number of the jll should match the version of the source. This is not always the case because sometimes the version number is multiplied by 100 and some version offset is applied.
It would be good if this could be documented.

Some context:

I am trying to understand how I could recompute the version number of the source from the version number of the jll in a generic way. Is there some indicator from the JLL whether or not this version offset was applied?

My initial use case is to fix the same version from the JLL as I would get from Conda so that the python and Julia packages would play nicely from the same process

[t-bltg]

I'm also interested in a normalization of offseted version numbers.

I started using a 1000 multiplier for the patch version of some recipes, but I've also seen 100 in other Yggdrasil recipes.

I'm surprised this hasn't been discussed before.
Having the ygg version going out of sync with the upstream version is a pain, and since BinaryBuilder does not allow suffixes such as 1.2.3+5 for yggdrasil build numbers, we are left with finding an acceptable alternate / normalized solution.

using Test

function yggdrasil_version(version::VersionNumber, offset::VersionNumber)
    max_offset = v"10.100.1000"
    @assert offset < max_offset
    VersionNumber(
        max_offset.major * version.major + offset.major,
        max_offset.minor * version.minor + offset.minor,
        max_offset.patch * version.patch + offset.patch
    )
end

function upstream_version(version::VersionNumber)
    max_offset = v"10.100.1000"
    upstream_major, offset_major = divrem(version.major, max_offset.major)
    upstream_minor, offset_minor = divrem(version.minor, max_offset.minor)
    upstream_patch, offset_patch = divrem(version.patch, max_offset.patch)
    offset = VersionNumber(offset_major, offset_minor, offset_patch)
    @info offset
    @assert offset < max_offset
    VersionNumber(upstream_major, upstream_minor, upstream_patch)
end

ups_version = v"123.456.78"  # upstream version
ygg_offset = v"1.50.753"  # arbitrary offset
ygg_version = yggdrasil_version(ups_version, ygg_offset)  # Yggdrasil version

@show ygg_version
@test upstream_version(ygg_version) == ups_version