[gentoo-dev] [PATCH] glep-0068: Add new <stabilization-candidates/> element

[Michał Górny]

Signed-off-by: Michał Górny <mgorny@g.o>
---
 glep-0068.rst | 62 ++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 59 insertions(+), 3 deletions(-)

diff --git a/glep-0068.rst b/glep-0068.rst
index d8fc379..5b7e2b9 100644
--- a/glep-0068.rst
+++ b/glep-0068.rst
@@ -4,10 +4,10 @@ Title: Package and category metadata
 Author: Michał Górny <mgorny@g.o>
 Type: Standards Track
 Status: Final
-Version: 1.1
+Version: 1.2
 Created: 2016-03-14
-Last-Modified: 2020-05-06
-Post-History: 2016-03-16, 2018-02-20
+Last-Modified: 2020-09-16
+Post-History: 2016-03-16, 2018-02-20, 2020-09-16
 Content-Type: text/x-rst
 Requires: 67
 Replaces: 34, 46, 56
@@ -149,6 +149,10 @@ element can contain, in any order:
   languages (at most one for each language), as detailed
   in `Slot descriptions`_.
 
+- at most one ``<stabilization-candidates/>`` element containing version
+  constraints used to determine stabilization candidates, as detailed
+  in `Stabilization candidates`_.
+
 - zero or more ``<stabilize-allarches/>`` elements, possibly restricted
   to specific package versions (at most one for each version) whose presence
   indicates that the appropriate ebuilds are suitable for simultaneously
@@ -199,6 +203,25 @@ The ``<slots/>`` element can contain the following elements:
 - at most one ``<subslots/>`` element describing the role of subslots (all
   of them) as text.
 
+Stabilization candidates
+~~~~~~~~~~~~~~~~~~~~~~~~
+Each ``<stabilization-candidates/>`` element describes version
+constraints used to determine package versions eligible
+for stabilization.  Should this element be missing, the tooling assumes
+a default of any version with any keywords present (i.e. the equivalent
+of ``>=0``).
+
+The ``<stabilization-candidates/>`` element can contain the following
+elements:
+
+- one or more ``<version/>`` elements, each containing a version
+  constraint in the format matching EAPI 0 dependency specification
+  with the package category and name parts omitted, e.g. ``<1.7``.
+  The tooling considers any ebuild version that satisfies the constraint
+  and has any keywords.  If multiple constraints are provided, every one
+  of them is matched separately, and multiple stabilization candidates
+  can be reported.
+
 USE flag descriptions
 ~~~~~~~~~~~~~~~~~~~~~
 Each ``<use/>`` element describes USE flags of a package (in specific
@@ -378,6 +401,39 @@ package version restrictions and maintainer descriptions were also implicitly
 allowed on them. Since neither of the two was allowed by GLEP 46, this
 specification disallows them.
 
+Stabilization candidates
+~~~~~~~~~~~~~~~~~~~~~~~~
+Version 1.2 of the specification adds stabilization candidate versions.
+The primary goal of this is to provide a more fine-grained control
+of tooling reporting stabilization candidates.  Previously, pkgcheck
+reported only the newest keyworded version that was eligible for
+stabilization according to the 30-day testing period.  This had two
+limitations.
+
+Firstly, it did not account for development branches properly
+and reported them as stabilization candidates.  While we could
+technically blacklist ``_alpha``, ``_beta``, ``_rc`` versions,
+this would not work for all packages.  Some GNOME and XFCE packages use
+odd numbers in minor version to indicate development branch.
+On the other hand, there are stagnant packages that stay in pre-release
+state for months, and stabilizing these versions also makes sense.
+
+Secondly, it did not account for software maintaining multiple parallel
+stable branches.  As soon as the newer version became eligible
+for stabilization, new releases of the older branches were not reported.
+In some cases, users are bound to old versions because of dependencies
+(e.g. on Python 2.7).
+
+The proposed ‘whitelist-override’ syntax aims to help with both cases.
+The default preserves current behavior.  A single override such
+as ``<1.7`` can be used to explicitly ignore development branch,
+and request stabilization candidates from earlier versions.  Multiple
+version constraints (say, ``<5.9`` and ``<5.5``) can be used to request
+monitoring multiple upstream branches.
+
+This information can also be consumed by users to opt-out of development
+versions and keep their systems running potential stable candidates.
+
 
 Backwards Compatibility
 =======================
-- 
2.28.0