[gentoo-dev] GLEP 83 "EAPI deprecation" update v2
Version 2. No material changes, but clarified wording and added an example. Thanks to robbat2 for his comments. Patch and full new text of the GLEP are attached below. From 97fbff191d6b9a896d875f88f303816f7804a768 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ulrich=20M=C3=BCller?= Date: Fri, 30 Aug 2024 18:09:59 +0200 Subject: [PATCH v2] glep-0083: Allow deprecation when only one newer EAPI exists MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Ulrich Müller --- glep-0083.rst | 31 --- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/glep-0083.rst b/glep-0083.rst index 38b4e57..5762d37 100644 --- a/glep-0083.rst +++ b/glep-0083.rst @@ -6,8 +6,8 @@ Type: Informational Status: Active Version: 1 Created: 2022-06-30 -Last-Modified: 2022-08-14 -Post-History: 2022-07-11, 2022-07-31 +Last-Modified: 2024-09-01 +Post-History: 2022-07-11, 2022-07-31, 2024-08-30, 2024-09-01 Content-Type: text/x-rst --- @@ -38,11 +38,12 @@ warn about this [#COUNCIL-20130409]_. A *banned EAPI* must no longer be used, neither for new ebuilds, nor for updating of existing ebuilds [#COUNCIL-20140311]_. -The Gentoo Council will deprecate an EAPI when +The Gentoo Council will deprecate an EAPI when one or more newer +Council-approved EAPIs are supported by the stable version of Portage, +namely -* two newer Council-approved EAPIs are supported by the stable version - of Portage, and -* one of them has been supported for 24 months. +* two newer EAPIs, one of them supported for at least 24 months, or +* one newer EAPI, supported for at least 48 months. The Gentoo Council will ban a deprecated EAPI when @@ -70,7 +71,9 @@ allow projects to support a longer upgrade path. Requiring two newer EAPIs before deprecation will allow ebuilds that are otherwise seldom updated to be bumped to the next but one EAPI -immediately. +immediately. However, deprecation of an EAPI should not be deferred +forever, so it can be effected after a longer waiting period of 48 +months even if only one newer EAPI exists at that point. A delay of 24 months between deprecation and ban will give ebuild authors enough time to update. This is especially relevant for @@ -81,6 +84,20 @@ ebuild updates (and bug reports requesting them) manageable, as a banned EAPI is sufficient reason for updating an ebuild. +Example +=== + +Under this policy, EAPI 7 will be deprecated when either + +* Portage has supported EAPI 8 for 24 months, and supports another + later EAPI (e.g. EAPI 9), or +* Portage has supported EAPI 8 for 48 months. + +Portage has supported EAPI 8 since 2021-07-05. The first condition +would be fulfilled after 2023-07-05, as soon as an EAPI 9 is also +supported. The second condition would be fulfilled after 2025-07-05. + + Backwards Compatibility === -- 2.46.0 --- GLEP: 83 Title: EAPI deprecation Author: Ulrich Müller Type: Informational Status: Active Version: 1 Created: 2022-06-30 Last-Modified: 2024-09-01 Post-History: 2022-07-11, 2022-07-31, 2024-08-30, 2024-09-01 Content-Type: text/x-rst --- Abstract Introduce standardized criteria for deprecation and banning of EAPIs. Motivation == So far, old EAPIs were deprecated by the Gentoo Council in an ad-hoc manner. No fixed criteria were used, resulting in unpredictable deprecation times after approval of newer EAPIs. Standardized criteria for deprecation and banning will make the life cycle of EAPIs more predictable. Specification = A *deprecated EAPI* is no longer required for the upgrade path of users' systems. Its use is discouraged, and tools like pkgcheck will warn about this [#COUNCIL-20130409]_. A *banned EAPI* must no longer be used, neither for new ebuilds, nor for updating of existing ebuilds [#COUNCIL-20140311]_. The Gentoo Council will deprecate an EAPI when one or more newer Council-approved EAPIs are supported by the stable version of Portage, namely * two newer EAPIs, one of them supported for at least 24 months, or * one newer EAPI, supported for at least 48 months. The Gentoo Council will ban a deprecated EAPI when * 24 months have passed since its deprecation, and * it is used by fewer than 5 % of ebuilds in the Gentoo repository. EAPIs used in profiles are outside the scope of this GLEP. Rationale = Timing of EAPI deprecation is a trade-off between different factors. On the one hand, the total number of EAPIs in active use should be limited; this will prevent the learning curve for new developers and contributors from becoming too steep and will help to reduce code complexity, e.g. in eclasses. On the other hand, an upgrade path to a stable system is guaranteed for one year, plus limited support for systems that are outdated more than a year [#COUNCIL-20091109]_. Therefore, previous EAPIs are still required during that time. A period of 24 months before deprecation has been
[gentoo-dev] GLEP 83 "EAPI deprecation" update
Deprecation of an EAPI should not be deferred forever. This update of GLEP 83 will allow it after a longer waiting period of 48 months even if only one newer EAPI would exist at that point. From a1177143b51a374d0acda06915047b7573203a84 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ulrich=20M=C3=BCller?= Date: Fri, 30 Aug 2024 18:09:59 +0200 Subject: [PATCH] glep-0083: Allow deprecation when only one newer EAPI exists MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Ulrich Müller --- glep-0083.rst | 9 ++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/glep-0083.rst b/glep-0083.rst index 38b4e57..f542170 100644 --- a/glep-0083.rst +++ b/glep-0083.rst @@ -6,7 +6,7 @@ Type: Informational Status: Active Version: 1 Created: 2022-06-30 -Last-Modified: 2022-08-14 +Last-Modified: 2024-08-30 Post-History: 2022-07-11, 2022-07-31 Content-Type: text/x-rst --- @@ -42,7 +42,8 @@ The Gentoo Council will deprecate an EAPI when * two newer Council-approved EAPIs are supported by the stable version of Portage, and -* one of them has been supported for 24 months. +* one of them has been supported for 24 months; or +* one newer Council-approved EAPI has been supported for 48 months. The Gentoo Council will ban a deprecated EAPI when @@ -70,7 +71,9 @@ allow projects to support a longer upgrade path. Requiring two newer EAPIs before deprecation will allow ebuilds that are otherwise seldom updated to be bumped to the next but one EAPI -immediately. +immediately. However, deprecation of an EAPI should not be deferred +forever, so it can be effected after a longer waiting period of 48 +months even if only one newer EAPI exists at that point. A delay of 24 months between deprecation and ban will give ebuild authors enough time to update. This is especially relevant for -- 2.46.0 --- GLEP: 83 Title: EAPI deprecation Author: Ulrich Müller Type: Informational Status: Active Version: 1 Created: 2022-06-30 Last-Modified: 2024-08-30 Post-History: 2022-07-11, 2022-07-31 Content-Type: text/x-rst --- Abstract Introduce standardized criteria for deprecation and banning of EAPIs. Motivation == So far, old EAPIs were deprecated by the Gentoo Council in an ad-hoc manner. No fixed criteria were used, resulting in unpredictable deprecation times after approval of newer EAPIs. Standardized criteria for deprecation and banning will make the life cycle of EAPIs more predictable. Specification = A *deprecated EAPI* is no longer required for the upgrade path of users' systems. Its use is discouraged, and tools like pkgcheck will warn about this [#COUNCIL-20130409]_. A *banned EAPI* must no longer be used, neither for new ebuilds, nor for updating of existing ebuilds [#COUNCIL-20140311]_. The Gentoo Council will deprecate an EAPI when * two newer Council-approved EAPIs are supported by the stable version of Portage, and * one of them has been supported for 24 months; or * one newer Council-approved EAPI has been supported for 48 months. The Gentoo Council will ban a deprecated EAPI when * 24 months have passed since its deprecation, and * it is used by fewer than 5 % of ebuilds in the Gentoo repository. EAPIs used in profiles are outside the scope of this GLEP. Rationale = Timing of EAPI deprecation is a trade-off between different factors. On the one hand, the total number of EAPIs in active use should be limited; this will prevent the learning curve for new developers and contributors from becoming too steep and will help to reduce code complexity, e.g. in eclasses. On the other hand, an upgrade path to a stable system is guaranteed for one year, plus limited support for systems that are outdated more than a year [#COUNCIL-20091109]_. Therefore, previous EAPIs are still required during that time. A period of 24 months before deprecation has been chosen, which is more than the required minimum and will allow projects to support a longer upgrade path. Requiring two newer EAPIs before deprecation will allow ebuilds that are otherwise seldom updated to be bumped to the next but one EAPI immediately. However, deprecation of an EAPI should not be deferred forever, so it can be effected after a longer waiting period of 48 months even if only one newer EAPI exists at that point. A delay of 24 months between deprecation and ban will give ebuild authors enough time to update. This is especially relevant for overlays and downstream distributions. An additional requirement for banning an EAPI is that fewer than 5 % of ebuilds are using the EAPI in question. This requirement is defined to help keep the number of ebuild updates (and bug reports requesting them) manageable, as a banned EAPI is sufficient reason for updating an ebuild. Backwards Compatibility === The following table compares the actual dates of deprecations and bans [#PMS-PROJECT]_ with the dates that wo
Re: [gentoo-dev] GLEP 83: EAPI deprecation
> On Sun, 31 Jul 2022, Thomas Bracht Laumann Jespersen wrote: > Minor language things, on the whole an easy document to read! >> Motivation >> == >> >> So far, old EAPIs were deprecated by the Gentoo Council in an ad-hoc >> manner. No fixed criteria were used, resulting in very different >> deprecation times after approval of newer EAPIs. Standardized >> criteria for deprecation and banning will make the life cycle of EAPIs >> more predictable. > "very different" could maybe be specified further. Something like > "inconsistent"/"unreliable"/"unpredictable" is more precise? >> >> The Gentoo Council will ban a deprecated EAPI when >> >> * 24 months have passed since its deprecation, and >> * it is used by less than 5 % of ebuilds in the Gentoo repository. > Should be "fewer than 5 %". >> >> A delay of 24 months between deprecation and ban will give ebuild >> authors enough time to update. This is especially relevant for >> overlays and downstream distributions. Since a banned EAPI is >> sufficient reason for updating an ebuild, an additional threshold of >> 5 % is required, in order to keep the number of such updates (and bug >> reports requesting them) manageable. > Two things: > "Since" has a temporal meaning, but is often used to mean "although". Maybe > "although" is a better word here? > I would drop the ", in order" and make it simply "[…] an additional threshold > of 5% is required to keep the number […]" Thanks, should be all fixed. Updated version will follow. Ulrich signature.asc Description: PGP signature
Re: [gentoo-dev] GLEP 83: EAPI deprecation
New version, with following changes: - Use a list for the deprecation criteria - CSV table converted into simple table, for better readability of the source code - Updated EAPI 6 data, slightly different method for fitting it --- GLEP: 83 Title: EAPI deprecation Author: Ulrich Müller Type: Informational Status: Draft Version: 1 Created: 2022-06-30 Last-Modified: 2022-07-31 Post-History: 2022-07-11, 2022-07-31 Content-Type: text/x-rst --- Abstract Introduce standardized criteria for deprecation and banning of EAPIs. Motivation == So far, old EAPIs were deprecated by the Gentoo Council in an ad-hoc manner. No fixed criteria were used, resulting in very different deprecation times after approval of newer EAPIs. Standardized criteria for deprecation and banning will make the life cycle of EAPIs more predictable. Specification = A *deprecated EAPI* is no longer required for the upgrade path of users' systems. Its use is discouraged, and tools like pkgcheck will warn about this [#COUNCIL-20130409]_. A *banned EAPI* must no longer be used, neither for new ebuilds, nor for updating of existing ebuilds [#COUNCIL-20140311]_. The Gentoo Council will deprecate an EAPI when * two newer Council-approved EAPIs are supported by the stable version of Portage, and * one of them has been supported for 24 months. The Gentoo Council will ban a deprecated EAPI when * 24 months have passed since its deprecation, and * it is used by less than 5 % of ebuilds in the Gentoo repository. EAPIs used in profiles are outside the scope of this GLEP. Rationale = Timing of EAPI deprecation is a trade-off between different factors. On the one hand, the total number of EAPIs in active use should be limited; this will prevent the learning curve for new developers and contributors from becoming too steep and will help to reduce code complexity, e.g. in eclasses. On the other hand, an upgrade path to a stable system is guaranteed for one year, plus limited support for systems that are outdated more than a year [#COUNCIL-20091109]_. Therefore, previous EAPIs are still required during that time. A period of 24 months before deprecation has been chosen, which is more than the required minimum and will allow projects to support a longer upgrade path. Requiring two newer EAPIs before deprecation will allow ebuilds that are otherwise seldom updated to be bumped to the next but one EAPI immediately. A delay of 24 months between deprecation and ban will give ebuild authors enough time to update. This is especially relevant for overlays and downstream distributions. Since a banned EAPI is sufficient reason for updating an ebuild, an additional threshold of 5 % is required, in order to keep the number of such updates (and bug reports requesting them) manageable. Backwards Compatibility === The following table compares the actual dates of deprecations and bans [#PMS-PROJECT]_ with the dates that would have resulted from the criteria proposed in this GLEP ("new date"). == === === == == === == == EAPI Portage Gentoo repo deprecated diff. banned diff. -- --- --- -- --- -- \ stable usage < 5 % actual date new datemonths actual date new datemonths == === === == == === == == 0 2005-12-26 2017-02-28 2014-02-25 2009-12-11 -50 2016-01-10 2017-02-28 +14 1 2007-12-11 2009-10-25 2013-04-09 2011-01-08 -27 2014-03-11 2013-01-08 -14 2 2009-01-08 2015-03-27 2013-04-09 2012-03-08 -13 2014-03-11 2015-03-27 +12 3 2010-03-08 2015-01-16 2014-02-25 2013-03-17 -11 2016-01-10 2015-03-17 -10 4 2011-03-17 2018-01-11 2015-10-11 2016-01-17 +3 2018-04-08 2018-01-17 -3 5 2012-12-11 2021-06-15 2018-05-13 2018-06-27 +1 2021-08-08 2021-06-15 -2 6 2016-01-17 2022-11-06 2021-07-11 2021-07-050 2023-07-05 [*]_ 7 2018-06-27 8 2021-07-05 == === === == == === == == .. [*] Extrapolated date, obtained by fitting data between 2021-01-01 and 2022-07-31 with an exponential function. References == .. [#COUNCIL-20130409] "EAPI deprecation", Gentoo Council meeting summary 2013-04-09 (https://projects.gentoo.org/council/meeting-logs/20130409-summary.txt). Note: The original quote says "Repoman" instead of "pkgcheck". .. [#COUNCIL-20140311] "Ban on EAPI 1 and 2 should extend to updating EAPI in existing ebuilds", Gentoo Council meeting summary 2014-03-11 (https://projects.gentoo.org/council/meeting-logs/20140311-summary.txt) .. [#COUNCIL-20091109] "Upgrade path for old s
Re: [gentoo-dev] GLEP 83: EAPI deprecation
> On 13 Jul 2022, at 19:50, Arthur Zamarin wrote: > > On 13/07/2022 11.12, Ulrich Mueller wrote: >>> On Mon, 11 Jul 2022, Ulrich Mueller wrote: >> >> >> So, any opinions? Should we go for the longer transition time (and make >> overlay maintainers happy), or for a shorter time so that we can tidy up >> eclasses sooner? >> >> Ulrich > > My personal take on this question. Faster deprecation of EAPI ebuilds in > ::gentoo repo (as we can control it), but longer time until we remove it > from eclasses. Note that I don't mean here deprecation, only removal. > > I think that with current EAPI>=6 state, the "weight of supporting" > EAPI=6 isn't very heavy, so some extra time for overlays will be nice. I > do know that I don't help a lot in eclass maintenance, so if I wrong in > this statement, I won't complain of course. > > Maybe (?) this will also help during bumps of old systems (not that we > care too much, as we give them along timeframe for this and they can use > snapshots of repo, but why not as an extra bonus). > Yeah, I broadly agree with this. Making things predictable for downstreams is important. Best, sam signature.asc Description: Message signed with OpenPGP
Re: [gentoo-dev] GLEP 83: EAPI deprecation
On 13/07/2022 11.12, Ulrich Mueller wrote: >> On Mon, 11 Jul 2022, Ulrich Mueller wrote: > > > So, any opinions? Should we go for the longer transition time (and make > overlay maintainers happy), or for a shorter time so that we can tidy up > eclasses sooner? > > Ulrich My personal take on this question. Faster deprecation of EAPI ebuilds in ::gentoo repo (as we can control it), but longer time until we remove it from eclasses. Note that I don't mean here deprecation, only removal. I think that with current EAPI>=6 state, the "weight of supporting" EAPI=6 isn't very heavy, so some extra time for overlays will be nice. I do know that I don't help a lot in eclass maintenance, so if I wrong in this statement, I won't complain of course. Maybe (?) this will also help during bumps of old systems (not that we care too much, as we give them along timeframe for this and they can use snapshots of repo, but why not as an extra bonus). -- Arthur Zamarin arthur...@gentoo.org Gentoo Linux developer (Python, Arch Teams, pkgcore stack, GURU) OpenPGP_signature Description: OpenPGP digital signature
Re: [gentoo-dev] GLEP 83: EAPI deprecation
> On Mon, 11 Jul 2022, Ulrich Mueller wrote: > Please find below the first draft of GLEP 83 "EAPI deprecation". > This tries to define criteria for deprecation and for banning of EAPIs > by the Council. > I have tried to model it in a way that the actual dates for at least > EAPIs 4 and 5 are reproduced within a few months. To this end, the > criteria depend on three parameters: > - time between EAPI n+1 support by stable Portage and deprecation > of EAPI n (24 months) > - time between deprecation and ban (24 months) > - fraction of ebuilds in the tree when banning (< 5 %, at present > corresponding to about 1500 ebuilds) > The first two parameters can be varied within a relatively wide range, > without much influence on the timing for EAPIs 4 and 5. Combinations > like 30/24 months, 30/18 months, 24/18 months, or even 36/12 months > would work as well. I guess the question there is if we prefer a longer > upgrade path and transition times, or a smaller number of EAPIs in the > tree. To get the discussion going, the crucial parameter is the time between deprecation and ban. If my extrapolated date for the number of EAPI 6 ebuilds falling below 5 % is at least somewhat accurate (2022-11-22), then EAPI 6 would be banned: - with 24 months time between deprecation and ban: July 2023, - with 18 months time between deprecation and ban: January 2023, and - with 12 months time between deprecation and ban: November 2022. I believe that this wouldn't much affect removal of ebuilds from the tree, but it might have other consequences. For example, it has been suggested that we link EAPI support in eclasses to that status, i.e. we wouldn't remove support until an EAPI becomes banned. So, any opinions? Should we go for the longer transition time (and make overlay maintainers happy), or for a shorter time so that we can tidy up eclasses sooner? Ulrich signature.asc Description: PGP signature
[gentoo-dev] GLEP 83: EAPI deprecation
Please find below the first draft of GLEP 83 "EAPI deprecation". This tries to define criteria for deprecation and for banning of EAPIs by the Council. I have tried to model it in a way that the actual dates for at least EAPIs 4 and 5 are reproduced within a few months. To this end, the criteria depend on three parameters: - time between EAPI n+1 support by stable Portage and deprecation of EAPI n (24 months) - time between deprecation and ban (24 months) - fraction of ebuilds in the tree when banning (< 5 %, at present corresponding to about 1500 ebuilds) The first two parameters can be varied within a relatively wide range, without much influence on the timing for EAPIs 4 and 5. Combinations like 30/24 months, 30/18 months, 24/18 months, or even 36/12 months would work as well. I guess the question there is if we prefer a longer upgrade path and transition times, or a smaller number of EAPIs in the tree. A rendered version (which especially makes the backwards compatibility table readable) can be found here: https://github.com/ulm/glep/blob/glep-eapi-deprecation/glep-0083.rst Comments please. Ulrich --- GLEP: 83 Title: EAPI deprecation Author: Ulrich Müller Type: Informational Status: Draft Version: 1 Created: 2022-06-30 Last-Modified: 2022-07-11 Post-History: 2022-07-11 Content-Type: text/x-rst --- Abstract Introduce standardized criteria for deprecation and banning of EAPIs. Motivation == So far, old EAPIs were deprecated by the Gentoo Council in an ad-hoc manner. No fixed criteria were used, resulting in very different deprecation times after approval of newer EAPIs. Standardized criteria for deprecation and banning will make the life cycle of EAPIs more predictable. Specification = A *deprecated EAPI* is no longer required for the upgrade path of users' systems. Its use is discouraged, and tools like pkgcheck will warn about this [#COUNCIL-20130409]_. A *banned EAPI* must no longer be used, neither for new ebuilds, nor for updating of existing ebuilds [#COUNCIL-20140311]_. The Gentoo Council will deprecate an EAPI when two newer EAPIs are supported by the stable version of Portage, and one of them has been supported for 24 months. The Gentoo Council will ban a deprecated EAPI when it is used by less than 5 % of ebuilds in the Gentoo repository, but no sooner than 24 months after its deprecation. EAPIs used in profiles are outside the scope of this GLEP. Rationale = Timing of EAPI deprecation is a trade-off between different factors. On the one hand, the total number of EAPIs in active use should be limited; this will prevent the learning curve for new developers and contributors from becoming too steep and will help to reduce code complexity, e.g. in eclasses. On the other hand, an upgrade path to a stable system is guaranteed for one year, plus limited support for systems that are outdated more than a year [#COUNCIL-20091109]_. Therefore, previous EAPIs are still required during that time. A period of 24 months before deprecation has been chosen, which is more than the required minimum and will allow projects to support a longer upgrade path. Requiring two newer EAPIs before deprecation will allow ebuilds that are otherwise seldom updated to be bumped to the next but one EAPI immediately. A delay of 24 months between deprecation and ban will give ebuild authors enough time to update. This is especially relevant for overlays and downstream distributions. Since a banned EAPI is sufficient reason for updating an ebuild, an additional threshold of 5 % is required, in order to keep the number of such updates (and bug reports requesting them) manageable. Backwards Compatibility === The following table compares the actual dates of deprecations and bans [#PMS-PROJECT]_ with the dates that would have resulted from the criteria proposed in this GLEP ("new date"). .. csv-table:: :header-rows: 2 :stub-columns: 1 :widths: auto :align: right EAPI,Portage,Gentoo repo,deprecated,deprecated,diff.,banned,banned,diff. ,stable,usage < 5 %,actual date,new date,months,actual date,new date,months 0,2005-12-26,2017-02-28,2014-02-25,2009-12-11,-50,2016-01-10,2017-02-28,+14 1,2007-12-11,2009-10-25,2013-04-09,2011-01-08,-27,2014-03-11,2013-01-08,-14 2,2009-01-08,2015-03-27,2013-04-09,2012-03-08,-13,2014-03-11,2015-03-27,+12 3,2010-03-08,2015-01-16,2014-02-25,2013-03-17,-11,2016-01-10,2015-03-17,-10 4,2011-03-17,2018-01-11,2015-10-11,2016-01-17,+3,2018-04-08,2018-01-17,-3 5,2012-12-11,2021-06-15,2018-05-13,2018-06-27,+1,2021-08-08,2021-06-15,-2 6,2016-01-17,2022-11-22 [*]_,2021-07-11,2021-07-05,0,,2023-07-05, 7,2018-06-27,,, 8,2021-07-05,,, .. [*] Extrapolated date, obtained by fitting data between 2021-01-01 and 2022-07-11 with an exponential function. References == .. [#COUNCIL-20130409] "EAPI deprecation", Gentoo Council meeting summary 2013-04-09 (https://pr