1 |
Update v3, thanks to Thomas Bracht Laumann Jespersen for grammatical |
2 |
corrections. |
3 |
|
4 |
|
5 |
--- |
6 |
GLEP: 83 |
7 |
Title: EAPI deprecation |
8 |
Author: Ulrich Müller <ulm@g.o> |
9 |
Type: Informational |
10 |
Status: Draft |
11 |
Version: 1 |
12 |
Created: 2022-06-30 |
13 |
Last-Modified: 2022-07-31 |
14 |
Post-History: 2022-07-11, 2022-07-31 |
15 |
Content-Type: text/x-rst |
16 |
--- |
17 |
|
18 |
|
19 |
Abstract |
20 |
======== |
21 |
|
22 |
Introduce standardized criteria for deprecation and banning of EAPIs. |
23 |
|
24 |
|
25 |
Motivation |
26 |
========== |
27 |
|
28 |
So far, old EAPIs were deprecated by the Gentoo Council in an ad-hoc |
29 |
manner. No fixed criteria were used, resulting in unpredictable |
30 |
deprecation times after approval of newer EAPIs. Standardized |
31 |
criteria for deprecation and banning will make the life cycle of EAPIs |
32 |
more predictable. |
33 |
|
34 |
|
35 |
Specification |
36 |
============= |
37 |
|
38 |
A *deprecated EAPI* is no longer required for the upgrade path of |
39 |
users' systems. Its use is discouraged, and tools like pkgcheck will |
40 |
warn about this [#COUNCIL-20130409]_. |
41 |
|
42 |
A *banned EAPI* must no longer be used, neither for new ebuilds, nor |
43 |
for updating of existing ebuilds [#COUNCIL-20140311]_. |
44 |
|
45 |
The Gentoo Council will deprecate an EAPI when |
46 |
|
47 |
* two newer Council-approved EAPIs are supported by the stable version |
48 |
of Portage, and |
49 |
* one of them has been supported for 24 months. |
50 |
|
51 |
The Gentoo Council will ban a deprecated EAPI when |
52 |
|
53 |
* 24 months have passed since its deprecation, and |
54 |
* it is used by fewer than 5 % of ebuilds in the Gentoo repository. |
55 |
|
56 |
EAPIs used in profiles are outside the scope of this GLEP. |
57 |
|
58 |
|
59 |
Rationale |
60 |
========= |
61 |
|
62 |
Timing of EAPI deprecation is a trade-off between different factors. |
63 |
On the one hand, the total number of EAPIs in active use should be |
64 |
limited; this will prevent the learning curve for new developers and |
65 |
contributors from becoming too steep and will help to reduce code |
66 |
complexity, e.g. in eclasses. |
67 |
|
68 |
On the other hand, an upgrade path to a stable system is guaranteed |
69 |
for one year, plus limited support for systems that are outdated more |
70 |
than a year [#COUNCIL-20091109]_. Therefore, previous EAPIs are still |
71 |
required during that time. A period of 24 months before deprecation |
72 |
has been chosen, which is more than the required minimum and will |
73 |
allow projects to support a longer upgrade path. |
74 |
|
75 |
Requiring two newer EAPIs before deprecation will allow ebuilds that |
76 |
are otherwise seldom updated to be bumped to the next but one EAPI |
77 |
immediately. |
78 |
|
79 |
A delay of 24 months between deprecation and ban will give ebuild |
80 |
authors enough time to update. This is especially relevant for |
81 |
overlays and downstream distributions. An additional requirement for |
82 |
banning an EAPI is that fewer than 5 % of ebuilds are using the EAPI |
83 |
in question. This requirement is defined to help keep the number of |
84 |
ebuild updates (and bug reports requesting them) managable, as a |
85 |
banned EAPI is sufficient reason for updating an ebuild. |
86 |
|
87 |
|
88 |
Backwards Compatibility |
89 |
======================= |
90 |
|
91 |
The following table compares the actual dates of deprecations and bans |
92 |
[#PMS-PROJECT]_ with the dates that would have resulted from the |
93 |
criteria proposed in this GLEP ("new date"). |
94 |
|
95 |
==== ========== =========== =========== ========== ====== =========== ========== ====== |
96 |
EAPI Portage Gentoo repo deprecated diff. banned diff. |
97 |
---- ---------- ----------- ----------------------- ------ ----------------------- ------ |
98 |
\ stable usage < 5 % actual date new date months actual date new date months |
99 |
==== ========== =========== =========== ========== ====== =========== ========== ====== |
100 |
0 2005-12-26 2017-02-28 2014-02-25 2009-12-11 -50 2016-01-10 2017-02-28 +14 |
101 |
1 2007-12-11 2009-10-25 2013-04-09 2011-01-08 -27 2014-03-11 2013-01-08 -14 |
102 |
2 2009-01-08 2015-03-27 2013-04-09 2012-03-08 -13 2014-03-11 2015-03-27 +12 |
103 |
3 2010-03-08 2015-01-16 2014-02-25 2013-03-17 -11 2016-01-10 2015-03-17 -10 |
104 |
4 2011-03-17 2018-01-11 2015-10-11 2016-01-17 +3 2018-04-08 2018-01-17 -3 |
105 |
5 2012-12-11 2021-06-15 2018-05-13 2018-06-27 +1 2021-08-08 2021-06-15 -2 |
106 |
6 2016-01-17 2022-11-06 2021-07-11 2021-07-05 0 2023-07-05 |
107 |
[*]_ |
108 |
7 2018-06-27 |
109 |
8 2021-07-05 |
110 |
==== ========== =========== =========== ========== ====== =========== ========== ====== |
111 |
|
112 |
.. [*] Extrapolated date, obtained by fitting data between 2021-01-01 |
113 |
and 2022-07-31 with an exponential function. |
114 |
|
115 |
|
116 |
References |
117 |
========== |
118 |
|
119 |
.. [#COUNCIL-20130409] "EAPI deprecation", |
120 |
Gentoo Council meeting summary 2013-04-09 |
121 |
(https://projects.gentoo.org/council/meeting-logs/20130409-summary.txt). |
122 |
Note: The original quote says "Repoman" instead of "pkgcheck". |
123 |
|
124 |
.. [#COUNCIL-20140311] "Ban on EAPI 1 and 2 should extend to updating |
125 |
EAPI in existing ebuilds", Gentoo Council meeting summary 2014-03-11 |
126 |
(https://projects.gentoo.org/council/meeting-logs/20140311-summary.txt) |
127 |
|
128 |
.. [#COUNCIL-20091109] "Upgrade path for old systems", |
129 |
Gentoo Council meeting summary 2009-11-09 |
130 |
(https://projects.gentoo.org/council/meeting-logs/20091109-summary.txt) |
131 |
|
132 |
.. [#PMS-PROJECT] Gentoo Package Manager Specification project |
133 |
(https://wiki.gentoo.org/wiki/Project:Package_Manager_Specification#EAPI_life_cycle) |
134 |
|
135 |
|
136 |
Copyright |
137 |
========= |
138 |
|
139 |
This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 |
140 |
International License. To view a copy of this license, visit |
141 |
https://creativecommons.org/licenses/by-sa/4.0/. |