Some notes on core.version_ranges:resolve_prereleases conf

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<tutorial_version_ranges_expressions>`,
 by default Conan does not match pre-release versions to ranges that don't specify it.
-Conan provides the :ref:`global.conf<reference_config_files_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<reference_config_files_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

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<resolve_prereleases_summary>`.
+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 <version_ranges_reference>`