Clarify baseline versioning

[Filoppi]

I think the wording here is a bit ambiguous and confusing for beginners. I had to spend quite a while browsing to get this information.
See my post here: microsoft/vcpkg#42075

[prmerger-automator]

@Filoppi : Thanks for your contribution! The author(s) have been notified to review your proposed change.

[learn-build-service-prod]

Learn Build status updates of commit 0b98d94:

✅ Validation status: passed

File	Status	Preview URL	Details
vcpkg/users/versioning.md	✅Succeeded	View

For more details, please refer to the build report.

For any questions, please:

• Try searching the learn.microsoft.com contributor guides
• Post your question in the Learn support channel

[vicroms]

I rewrote the paragraph a bit further. Do you think that this makes it even clearer?

[vicroms]

Suggested change

Baselines define a global version floor for what versions will be considered (unless specified elsewhere, the version associated with that baseline will be used). This enables top-level manifests to keep the entire graph of dependencies up-to-date without needing to individually specify direct [`"version>="`](#version-gte) constraints.

Baselines define a global version floor for every [port](../concepts/ports.md) in a [registry](../concepts/registries.md). In other words, ports have an implied `version>=` constraint on the version associated to the baseline; and unless a constraint is specified elsewhere, the version in the baseline gets installed. This enables top-level manifests to keep the entire graph of dependencies up to date without needing to specify [`"version>="`](#version-gte) constraints for each dependency.

[Filoppi]

@vicroms as a newcomer to vcpkg, unfortunately I don't think that is clearer. My only interests was version locking the packages, and I wanted to understand how to do it, and I found the documentation to be too technical on that stuff when it should be readable by anybody. I don't know what a "port" is. Or what the graph of dependencies is. So what I make out of that is that it simply forbids older versions but keeps using the latest (which is not the case).
Im always for ELI5 explanations but, up to you 🙂. Thanks for acknowledging this.

[vicroms]

@Filoppi

Thanks for the feedback. I modified the suggestion further to include more of the language you proposed in your original change. Unfortunately, there are nuances to how versioning works that cannot be explained without going into at least a bit of technical detail.

I don't know what a "port" is.

A port is the term we use to describe the set of files that tell vcpkg how to download, build, and install a library/package.

Or what the graph of dependencies is.

When you install a library, it often has dependencies (direct dependencies), and those dependencies can have their own dependencies (we call these, transitive dependencies). The graph of dependencies is the set of libraries that need to be installed in the appropriate order so that everything builds correctly (transitive dependencies first, then direct dependencies, and finally the requested library).

The problem with your original rewrite is that it suggests that if a constraint is added elsewhere, the baseline is ignored. But that is not actually the case, in reality, the baseline adds an "invisible" version>= constraint. It is possible that you define a constraint in your manifest (vcpkg.json file), but the baseline version is installed anyway.

For example:

• Baseline has foo at version 1.2.0 (this means that a "version>=": "1.2.0" constraint is invisibly added).
• Your manifest (vcpkg.json) has foo at "version>=": "1.0.0".

This creates two conditions >=1.0.0 and >=1.2.0 that need to be satisfied, the minimum version that could fulfil both constraints is 1.2.0, which means that the baseline version gets installed.

vcpkg can be forced to select 1.0.0 with the following methods:

• using overrides to force 1.0.0.
• using an older baseline where foo is at 1.0.0 (but this also downgrades every other library).
• using an overlay port which skips versioning resolution completely

[Filoppi]

@vicroms Just to further clarify. In the baseline case you mentioned above, if 1.3.0 came out, it wouldn't automatically be downloaded right?

[vicroms]

@vicroms Just to further clarify. In the baseline case you mentioned above, if 1.3.0 came out, it wouldn't automatically be downloaded right?

No, it wouldn't. You would need to use a newer baseline or upgrade the version constraint. The design principle is to never update versions without the users knowledge.

[Filoppi]

@vicroms Just to further clarify. In the baseline case you mentioned above, if 1.3.0 came out, it wouldn't automatically be downloaded right?

No, it wouldn't. You would need to use a newer baseline or upgrade the version constraint. The design principle is to never update versions without the users knowledge.

Right. My point is that most users would simply be interested in learning how to do that.
I created a vcpkg manifest manually, so it originally didn't have a baseline version specified, which would have meant there was no version constraints, it'd always use the latest one (AFAIK).
All I wanted to know what that the baseline locked the packages to a specific version, but I found everything I read about it very confusing from the point of view of a beginner.
So maybe, if you don't wanna change the "baseline" description, add a new paragraph which is TD;DR; How to simply lock to a fixed version and specify that adding a baseline definition (and nothing else) will achieve that :). Thx