Signed-off-by: Michał Górny <mgo...@gentoo.org> --- 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 <mgo...@gentoo.org> 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
