commit: 119d8ef975320ab37c642d5ff804fade8b2ad232 Author: Ulrich Müller <ulm <AT> gentoo <DOT> org> AuthorDate: Thu Jun 30 15:03:23 2022 +0000 Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org> CommitDate: Mon Jul 11 18:58:10 2022 +0000 URL: https://gitweb.gentoo.org/data/glep.git/commit/?id=119d8ef9
glep-0083: Initial draft of EAPI deprecation GLEP Bug: https://bugs.gentoo.org/855362 Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org> glep-0083.rst | 134 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) diff --git a/glep-0083.rst b/glep-0083.rst new file mode 100644 index 0000000..3f9b259 --- /dev/null +++ b/glep-0083.rst @@ -0,0 +1,134 @@ +--- +GLEP: 83 +Title: EAPI deprecation +Author: Ulrich Müller <u...@gentoo.org> +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://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 systems", + Gentoo Council meeting summary 2009-11-09 + (https://projects.gentoo.org/council/meeting-logs/20091109-summary.txt) + +.. [#PMS-PROJECT] Gentoo Package Manager Specification project + (https://wiki.gentoo.org/wiki/Project:Package_Manager_Specification#EAPI_life_cycle) + + +Copyright +========= + +This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 +International License. To view a copy of this license, visit +https://creativecommons.org/licenses/by-sa/4.0/.
