From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp.gentoo.org (woodpecker.gentoo.org [140.211.166.183]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits)) (No client certificate requested) by finch.gentoo.org (Postfix) with ESMTPS id 1E8BA158074 for ; Thu, 19 Jun 2025 17:34:09 +0000 (UTC) Received: from lists.gentoo.org (bobolink.gentoo.org [140.211.166.189]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange x25519) (No client certificate requested) (Authenticated sender: relay-lists.gentoo.org@gentoo.org) by smtp.gentoo.org (Postfix) with ESMTPSA id 08887341F75 for ; Thu, 19 Jun 2025 17:34:09 +0000 (UTC) Received: from bobolink.gentoo.org (localhost [127.0.0.1]) by bobolink.gentoo.org (Postfix) with ESMTP id 9365C110509; Thu, 19 Jun 2025 17:33:23 +0000 (UTC) Received: from smtp.gentoo.org (woodpecker.gentoo.org [140.211.166.183]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange x25519) (No client certificate requested) by bobolink.gentoo.org (Postfix) with ESMTPS id E02AF1104D9 for ; Thu, 19 Jun 2025 17:33:22 +0000 (UTC) Received: from urania (p200300cbaf469a001bbaba895197cde8.dip0.t-ipconnect.de [IPv6:2003:cb:af46:9a00:1bba:ba89:5197:cde8]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange secp256r1 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) (Authenticated sender: ulm) by smtp.gentoo.org (Postfix) with ESMTPSA id E1AEA341EFE; Thu, 19 Jun 2025 17:33:21 +0000 (UTC) From: =?utf-8?Q?Ulrich_M=C3=BCller?= To: gentoo-dev@lists.gentoo.org Subject: [gentoo-dev] GLEP 83 update: Support for EAPIs by package managers Date: Thu, 19 Jun 2025 19:33:17 +0200 Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-dev@lists.gentoo.org Reply-to: gentoo-dev@lists.gentoo.org X-Auto-Response-Suppress: DR, RN, NRN, OOF, AutoReply MIME-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha256; protocol="application/pgp-signature" X-Archives-Salt: 3bed52f4-cf56-4f06-ba67-b48c5f2d5e24 X-Archives-Hash: fa87f06f6dff0b14a8779c1ecd337f7a --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Please find below an updated version of GLEP 83, with a new section "Support for EAPIs by package managers". This will give some guidelines when package managers can drop support for old EAPIs, with rather long transition times. A separate message with the patch will follow. Ulrich =2D-- GLEP: 83 Title: EAPI deprecation Author: Ulrich M=C3=BCller Type: Informational Status: Active Version: 2 Created: 2022-06-30 Last-Modified: 2025-06-19 Post-History: 2022-07-11, 2022-07-31, 2024-08-30, 2024-09-01, 2025-06-19 Content-Type: text/x-rst =2D-- Abstract =3D=3D=3D=3D=3D=3D=3D=3D Introduce standardized criteria for deprecation and banning of EAPIs. Motivation =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D 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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D Use of EAPIs in the Gentoo repository =2D------------------------------------ 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 section. Support for EAPIs by package managers =2D------------------------------------ Package managers may drop (or omit) support for an EAPI only when all of the following conditions apply: * The EAPI was deprecated at least 10 years ago, * it has not been used by any ebuild in the Gentoo repository for the past 5 years, and * it has not been used by any profile in the Gentoo repository for the past 2 years. It is recommended that unmerging of old packages be supported indefinitely. Rationale =3D=3D=3D=3D=3D=3D=3D=3D=3D 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. Similar considerations apply to support of EAPIs by package managers. Supporting legacy EAPIs imposes ongoing maintenance costs; accumulation of EAPI-specific conditionals makes the code harder to read and maintain. Also, unused code paths tend to "bit rot" and see less testing over time. Notably, at the time of writing, EAPIs 0 to 2 are broken in Portage [#BUG-875353]_. Conversely, removing support for an EAPI from the package manager can be disruptive for users. Unofficial overlays and private repositories often continue using older EAPIs long after their removal from the main tree. Therefore, the timeline for dropping package-manager support is more generous than that for use of EAPIs in repositories. Finally, dropping unmerge support could block upgrades of outdated systems. Therefore, unmerging of packages with legacy EAPIs should stay supported indefinitely unless there is a compelling technical reason for its removal. Example =3D=3D=3D=3D=3D=3D=3D 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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D 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"). =3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D = =3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D =3D=3D=3D=3D=3D=3D EAPI Portage Gentoo repo deprecated diff. banned = diff. =2D--- ---------- ----------- ----------------------- ------ ---------= -------------- ------ \ stable usage < 5 % actual date new date months actual date= new date months =3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D = =3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D =3D=3D=3D=3D=3D=3D 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-05 0 = 2023-07-05 [*]_ 7 2018-06-27 8 2021-07-05 =3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D = =3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D =3D=3D=3D=3D=3D=3D .. [*] Extrapolated date, obtained by fitting data between 2021-01-01 and 2022-07-31 with an exponential function. References =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D .. [#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) .. [#BUG-875353] Bug 875353 - EAPI 0 ebuilds won't pass QA because ${ED} variable is empty and read only (https://bugs.gentoo.org/875353) .. [#PMS-PROJECT] Gentoo Package Manager Specification project (https://wiki.gentoo.org/wiki/Project:Package_Manager_Specification#EAPI= _life_cycle) Copyright =3D=3D=3D=3D=3D=3D=3D=3D=3D 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/. --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQFDBAEBCAAtFiEEtDnZ1O9xIP68rzDbUYgzUIhBXi4FAmhUSd0PHHVsbUBnZW50 b28ub3JnAAoJEFGIM1CIQV4uzUQH/iqxzDV2qjiPf/9Wk9bGgJaOKyffCjpAMv6F 4bF7R2ijYN2DMJNpOHNEbhuDrW3wZ8JSCXxk2N57XCmA0aN+8BP2DE/bwGgqt/bn RruZPhoPmfbptWVfAULyg8PHr9JYOoLRqXyWBj6bqbGs0X4JZf2FcBbbJc/CHsvs WfduQ9xNgHjyt90LLQ6NhwEVUkGgF4PbnOfDZxPeG4vCtYZkurqmDB4HYFaoQ/3s sIabOdEcGQjMB+MOOP1AzahwWO6yLgfEFRlmX41jt+ljPlcnybAwOeAj+HBZubzj U3L+kf/ISXyvcs5ddA8UJxSUC6mBGWcyW7GXM1NzijTkxY2weAA= =wLvx -----END PGP SIGNATURE----- --=-=-=--