From c8965b5a5e5f50c9083b05746715662d76b2056d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Abril=20Rinc=C3=B3n=20Blanco?= Date: Wed, 13 Aug 2025 00:36:12 +0200 Subject: [PATCH] Some notes on core.version_ranges:resolve_prereleases conf --- devops/versioning/resolve_prereleases.rst | 14 ++++++++++++-- tutorial/versioning/version_ranges.rst | 7 ++++--- 2 files changed, 16 insertions(+), 5 deletions(-) diff --git a/devops/versioning/resolve_prereleases.rst b/devops/versioning/resolve_prereleases.rst index a5366c094914..65a2c902b186 100644 --- a/devops/versioning/resolve_prereleases.rst +++ b/devops/versioning/resolve_prereleases.rst @@ -10,8 +10,18 @@ before it's released to have a change to validate the new version ahead of time. At first glance, it could be expected that the new version matches our range if it intersect it, but :ref:`as described in the version ranges tutorial`, by default Conan does not match pre-release versions to ranges that don't specify it. -Conan provides the :ref:`global.conf` ``core.version_ranges:resolve_prereleases``, -which when set to ``True``, enables pre-release matching in version ranges. + +Conan provides the :ref:`global.conf` ``core.version_ranges:resolve_prereleases`` conf, +a tri-state configuration option that controls if version ranges should resolve to pre-releases. + +When _not_ set, the default behavior is to listen to the version range expression, and only match +if the version range explicitly allows pre-release versions, like for ``[>=1 <2, include_prerelease]``. + +If the ``include_prerelease`` flag is not specified, pre-release versions are ignored in this case. + +When set to ``False``, it will not match pre-release versions, even if the version range expression allows it. + +When set to ``True``, it globally enables pre-release matching in version ranges, even if the version range expression does not explicitly allow it. This avoids having to modify and export the recipes of your dependency graph, which would become unfeasible for large ones. This conf has the added benefit of affecting the whole dependency graph, so that if any of our dependencies also define diff --git a/tutorial/versioning/version_ranges.rst b/tutorial/versioning/version_ranges.rst index 1f3868361dd8..28489afe1aa9 100644 --- a/tutorial/versioning/version_ranges.rst +++ b/tutorial/versioning/version_ranges.rst @@ -165,13 +165,14 @@ There is the possibility to use string-matching over the end of the string to si Finally, note that pre-releases are not resolved by default. The way to include them in the range is to explicitly enable them with either the ``include_prerelease`` option (``requires = "pkg/[>1 <2, include_prerelease]"``), -or via the ``core.version_ranges:resolve_prereleases=True`` configuration. In this example, 1.0-pre.1 and 1.5.1-pre1 will be included, -but 2.0-pre1 would be excluded. +or via the ``core.version_ranges:resolve_prereleases=True`` configuration, +:ref:`which you can read more about here`. +In this example, 1.0-pre.1 and 1.5.1-pre1 will be included, but 2.0-pre1 would be excluded. .. note:: While it is possible to hardcode the ``include_prerelease`` in the ``requires`` version range, it is not recommended generally. Pre-releases should be opt-in, and controlled by the user, who decides if they want to use pre-releases. - Also, note that the ``include_prereleases`` receives no argument, hence it's not possible to deactivate prereleases with ``include_prerelease=False``. + Also, note that the ``include_prerelease`` receives no argument, hence it's not possible to deactivate prereleases with ``include_prerelease=False``. For more information about valid range expressions go to :ref:`Requires reference `