From 29b8fed82b459e5e3d070da84bd8186abd5fd337 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rub=C3=A9n=20Rinc=C3=B3n=20Blanco?= Date: Tue, 7 Nov 2023 11:36:19 +0100 Subject: [PATCH] Add some warnings for include_prereleases option and fix its documentation (#3437) Co-authored-by: Carlos Zoido --- tutorial/versioning/version_ranges.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/tutorial/versioning/version_ranges.rst b/tutorial/versioning/version_ranges.rst index c73558f6f55c..a6e6436222bb 100644 --- a/tutorial/versioning/version_ranges.rst +++ b/tutorial/versioning/version_ranges.rst @@ -152,11 +152,14 @@ It is also possible to apply multiple conditions with the OR operator, like ``re but this kind of complex expressions is not recommended in practice and should only be used in very extreme cases. Finally, note that pre-releases are not resolved by default. The way to include them in the range is to -explicitly define it like ``requires = "pkg/[>=1 <2, include_prerelease]"``. This will include 1.0-pre.1 and 1.5.1-pre1, but exclude 2.0-pre1. +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. -While it is possible to hardcode the ``include_prerelease`` in the ``requires`` version, it is not recommended in the general -case. Pre-releases should be opt-in, and it should be controlled by the user, who is the one to decide if they want to -use pre-releases or not. This can be done defining the configuration ``core.version_ranges:resolve_prereleases``. +.. 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``. For more information about valid range expressions go to :ref:`Requires reference `