[gentoo-dev] How shall we name the EAPI 6 patch applying function?

[Michał Górny]

Hello all,

Wrt bug #463692 [1] we'd like to add a default src_prepare() in EAPI 6,
with PATCHES array and user patches support. For that reason, I've
requested in bug #463768 [2], that the function used to apply
the patches would be public -- so that users and eclasses could use it
consequently.

After some discussion on the relevant bug we came to the conclusion
that the epatch function is relentlessly bloated. It provides a lot
of features which are either already discouraged by its maintainer
(arch-prefixed patches), result in widespread QA issues (compressed
patch support) or is just too hard to implement reasonably.

For that reason, the new function will most likely support
the following:

a) patch files can be specified directly or through a directory
   in which *all* files will be applied in lexical order,

b) patches will be applied with -p1 unless overrode via direct
   arguments to patch applying function.

Rationale will follow. Since that functionality is very limited
compared to the epatch function, we will keep the old one in the eclass
for anyone really needing it. However, we need a name for the new
function.

Therefore, I ask you: how should we name the new (and simpler) patch
applying function which will be provided in EAPI 6?

[1]:https://bugs.gentoo.org/show_bug.cgi?id=463692
[2]:https://bugs.gentoo.org/show_bug.cgi?id=463768


Please note that the following rationale is assembled mostly from my
opinion and understanding of the others. Please do not take is
as an official Gentoo statement.

Short rationale:

1) automatic -p* support has seen most effort to keep in the spec.
However, there are a few important issues with it which outweigh
the usefulness of it:

* inability to know what intended patchlevel was can result in patches
  being applied to wrong files (e.g. when patch stops to apply
  to the intended file or start to apply to an unintended file with
  a lower patchlevel).

* the patches stored in the tree can't be easily reused upstream
  or by users since 'epatch' is limited to ebuild scope.

* the current implementation of epatch results in hard-to-read error
  output (you have to grep for the 'most proper' run).

This also implies that due to a new QA policy, Gentoo tree will consist
only of patches adjusted to be used with '-p1'. If nobody steps up
earlier, I will write a tool to fix patches to proper patchlevel.


2) compressed patch support is likely the most misused feature
in epatch. This is because in the most cases it was used:

* (in Sunrise overlay) to apply compressed patches from ${FILESDIR} --
  where storing compressed files there is a violation of QA policy.

* to apply compressed patches from ${DISTDIR} -- when src_unpack()
  has uncompressed the patches to ${WORKDIR} already.

Considering that the most compressed patches will either be downloaded
as compressed files or compressed archives, the responsibility for
unpacking them will fall on src_unpack(). Therefore, we believe that
there's no need for additional layer of complexity here.


3) support for directories was one of the most obfuscated features
of epatch. It included a number of adjustment variables like
EPATCH_SUFFIX, EPATCH_FORCE (where nobody could guess its meaning),
EPATCH_EXCLUDE and the discouraged arch-prefixed patches.

I've taken a quick grep of the Gentoo ebuild tree and the Gentoo patch
tree, and it seems that:

* only sys-libs/glibc seems to be still using arch-conditional patching.

* most of the patch directories consist of files prefixed by ordering
  number, suffixed by either '.patch' or '.diff'.

* some of the patch trees use Debian-style patches. That is, randomly
  named files with 'series' file determining the order of applying.

We've chosen the common solution which will work correctly for most
of the ebuilds with no need for additional control variables. Other
cases will either need to use globs to choose files directly,
or the eclass-defined epatch function.


I hope I covered all the main points. If I missed something, please let
me know.

-- 
Best regards,
Michał Górny