[gentoo-dev] GLEP 83: EAPI deprecation

[gentoo-dev] GLEP 83: EAPI deprecation

[Ulrich Mueller]

[-- Attachment #1: Type: text/plain, Size: 6064 bytes --]

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 <ulm@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/.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 507 bytes --]

Re: [gentoo-dev] GLEP 83: EAPI deprecation

[Ulrich Mueller]

[-- Attachment #1: Type: text/plain, Size: 1895 bytes --]

>>>>> 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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 507 bytes --]

Re: [gentoo-dev] GLEP 83: EAPI deprecation

[Arthur Zamarin]

[-- Attachment #1.1: Type: text/plain, Size: 1083 bytes --]

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
arthurzam@gentoo.org
Gentoo Linux developer (Python, Arch Teams, pkgcore stack, GURU)

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [gentoo-dev] GLEP 83: EAPI deprecation

[Sam James]

[-- Attachment #1: Type: text/plain, Size: 1169 bytes --]



> On 13 Jul 2022, at 19:50, Arthur Zamarin <arthurzam@gentoo.org> 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


[-- Attachment #2: Message signed with OpenPGP --]
[-- Type: application/pgp-signature, Size: 358 bytes --]

Re: [gentoo-dev] GLEP 83: EAPI deprecation

[Ulrich Mueller]

[-- Attachment #1: Type: text/plain, Size: 5638 bytes --]

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 <ulm@gentoo.org>
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 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-06   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-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 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/.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 507 bytes --]

Re: [gentoo-dev] GLEP 83: EAPI deprecation

[Thomas Bracht Laumann Jespersen]

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 […]"

-- Thomas

Re: [gentoo-dev] GLEP 83: EAPI deprecation

[Ulrich Mueller]

[-- Attachment #1: Type: text/plain, Size: 1575 bytes --]

>>>>> 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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 507 bytes --]

[gentoo-dev] GLEP 83 [v3]: EAPI deprecation

[Ulrich Mueller]

[-- Attachment #1: Type: text/plain, Size: 5579 bytes --]

Update v3, thanks to Thomas Bracht Laumann Jespersen for grammatical
corrections.


---
GLEP: 83
Title: EAPI deprecation
Author: Ulrich Müller <ulm@gentoo.org>
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 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.

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.

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) managable, 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 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 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-06   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-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 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/.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 507 bytes --]

[gentoo-dev] Re: GLEP 83 [v3]: EAPI deprecation

[Ulrich Mueller]

[-- Attachment #1: Type: text/plain, Size: 580 bytes --]

>>>>> On Sun, 31 Jul 2022, Ulrich Mueller wrote:

> 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) managable, as a
> banned EAPI is sufficient reason for updating an ebuild.

s/managable/manageable/

Fixed in Git (but no repost).

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 507 bytes --]

[gentoo-dev] Re: GLEP 83 [v3]: EAPI deprecation

[Duncan]

Ulrich Mueller posted on Sun, 31 Jul 2022 23:26:13 +0200 as excerpted:

> Update v3

One language thing and two possible clarifications.

> ---
> GLEP: 83 Title: EAPI deprecation
> Author: Ulrich Müller <ulm@gentoo.org>
> 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
> ---

> 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 fewer
> than 5 % of ebuilds in the Gentoo repository.

The first possible clarification fits here (I think).  Something like:

This GLEP is intended as a policy reference guide for EAPI minimum effective
times.  Despite the statistical qualifications listed here no EAPI
will be deprecated or banned without specific Gentoo Council action.

(While this is implied by the "Gentoo Council will..." wording, making it
explicit could prevent later confusion/controversy.)

> 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.

The language point:

Am I the only one for whom the omission of "from" makes the sentence read
smoother?  (Maybe it's a regional English thing?)

; this will prevent the learning curve [...] from becoming too steep...

; this will prevent the learning curve [...] becoming too steep...

> 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.  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) managable, as a banned EAPI is
> sufficient reason for updating an ebuild.

The second possible clarification seems to fit about here, but may require
a bit of adjustment to the text above it.

The two 24-month times are effectively additive, yielding a total 48 months
minimum between addition of an EAPI and banning of the previous one.  Given
past EAPI history of at minimum a year between EAPI introductions that should
yield a minimum three years of active EAPI life before deprecation, one year
minimum as the newest EAPI plus two years before deprecation, plus two years
of deprecation, for five years total EAPI life before ban.

(This isn't entirely necessary but makes explicit the answer to one of my first
questions reading the proposal.  YMMV.  I debated spec vs rational, but decided
rational was a better fit.)

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman

Re: [gentoo-dev] GLEP 83 [v3]: EAPI deprecation

[Sam James]

[-- Attachment #1: Type: text/plain, Size: 4742 bytes --]



> On 1 Aug 2022, at 22:24, Duncan <1i5t5.duncan@cox.net> wrote:
> 
> Ulrich Mueller posted on Sun, 31 Jul 2022 23:26:13 +0200 as excerpted:
> 
>> Update v3
> 
> One language thing and two possible clarifications.
> 
>> ---
>> GLEP: 83 Title: EAPI deprecation
>> Author: Ulrich Müller <ulm@gentoo.org>
>> 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
>> ---
> 
>> 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 fewer
>> than 5 % of ebuilds in the Gentoo repository.
> 
> The first possible clarification fits here (I think).  Something like:
> 
> This GLEP is intended as a policy reference guide for EAPI minimum effective
> times.  Despite the statistical qualifications listed here no EAPI
> will be deprecated or banned without specific Gentoo Council action.
> 
> (While this is implied by the "Gentoo Council will..." wording, making it
> explicit could prevent later confusion/controversy.)

If anything, this might make things more confusing, given it implies
the Council can deviate if it wants.

> 
>> 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.
> 
> The language point:
> 
> Am I the only one for whom the omission of "from" makes the sentence read
> smoother?  (Maybe it's a regional English thing?)
> 
> ; this will prevent the learning curve [...] from becoming too steep...
> 
> ; this will prevent the learning curve [...] becoming too steep...
> 

It reads slightly smoother without "from" but I didn't notice it when
reading myself.

I guess we can drop it.

>> 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.  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) managable, as a banned EAPI is
>> sufficient reason for updating an ebuild.
> 
> The second possible clarification seems to fit about here, but may require
> a bit of adjustment to the text above it.
> 
> The two 24-month times are effectively additive, yielding a total 48 months
> minimum between addition of an EAPI and banning of the previous one.  Given
> past EAPI history of at minimum a year between EAPI introductions that should
> yield a minimum three years of active EAPI life before deprecation, one year
> minimum as the newest EAPI plus two years before deprecation, plus two years
> of deprecation, for five years total EAPI life before ban.
> 
> (This isn't entirely necessary but makes explicit the answer to one of my first
> questions reading the proposal.  YMMV.  I debated spec vs rational, but decided
> rational was a better fit.)
> 
> --
> Duncan - List replies preferred.   No HTML msgs.
> "Every nonfree program has a lord, a master --
> and if you use the program, he is your master."  Richard Stallman
> 
> 


[-- Attachment #2: Message signed with OpenPGP --]
[-- Type: application/pgp-signature, Size: 358 bytes --]

Re: [gentoo-dev] GLEP 83 [v3]: EAPI deprecation

[Ulrich Mueller]

[-- Attachment #1: Type: text/plain, Size: 882 bytes --]

>>>>> On Tue, 02 Aug 2022, Sam James wrote:

>> On 1 Aug 2022, at 22:24, Duncan <1i5t5.duncan@cox.net> wrote:
>> 
>> The language point:
>> 
>> Am I the only one for whom the omission of "from" makes the sentence read
>> smoother?  (Maybe it's a regional English thing?)
>> 
>> ; this will prevent the learning curve [...] from becoming too steep...
>> 
>> ; this will prevent the learning curve [...] becoming too steep...

> It reads slightly smoother without "from" but I didn't notice it when
> reading myself.

> I guess we can drop it.

But is it grammatically correct with the "from"?
https://www.macmillandictionary.com/dictionary/british/prevent
seems to suggest so:

| The verb *prevent* is never followed by an infinitive.
| Use the patterns *prevent someone/something doing something*
| or *prevent someone/something from doing something* [...]

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 507 bytes --]

Re: [gentoo-dev] Re: GLEP 83 [v3]: EAPI deprecation

[Ulrich Mueller]

[-- Attachment #1: Type: text/plain, Size: 1408 bytes --]

>>>>> On Mon, 01 Aug 2022, Duncan  wrote:

> The first possible clarification fits here (I think).  Something like:

> This GLEP is intended as a policy reference guide for EAPI minimum effective
> times.  Despite the statistical qualifications listed here no EAPI
> will be deprecated or banned without specific Gentoo Council action.

> (While this is implied by the "Gentoo Council will..." wording, making it
> explicit could prevent later confusion/controversy.)

> [...]

> The second possible clarification seems to fit about here, but may require
> a bit of adjustment to the text above it.

> The two 24-month times are effectively additive, yielding a total 48 months
> minimum between addition of an EAPI and banning of the previous one.  Given
> past EAPI history of at minimum a year between EAPI introductions that should
> yield a minimum three years of active EAPI life before deprecation, one year
> minimum as the newest EAPI plus two years before deprecation, plus two years
> of deprecation, for five years total EAPI life before ban.

> (This isn't entirely necessary but makes explicit the answer to one of my first
> questions reading the proposal.  YMMV.  I debated spec vs rational, but decided
> rational was a better fit.)

I'd rather keep the text concise. For the first suggestion, the wording
already implies it. For the second one, people can do that maths
themselves.

Ulrich

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 507 bytes --]