commit: dcb57d688530aa1af4193aaec350d6d7f571c6cf
Author: Thomas Bracht Laumann Jespersen <t <AT> laumann <DOT> xyz>
AuthorDate: Sun Mar 27 20:17:34 2022 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Apr 6 18:40:39 2022 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=dcb57d68
ebuild-writing/patches: Add "Conditional patching" section
The added section under "Patches" tries to describe what patches are
intended for and why conditional patching should be avoided.
It was pointed out in a PR review that conditional patching in general
should be avoided as it introduces more variance and can make it harder
to debug breakage if a patch is only applied under certain conditions
(USE flags being the primary example).
Signed-off-by: Thomas Bracht Laumann Jespersen <t <AT> laumann.xyz>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
ebuild-writing/misc-files/patches/text.xml | 59 ++++++++++++++++++++++++++++++
1 file changed, 59 insertions(+)
diff --git a/ebuild-writing/misc-files/patches/text.xml
b/ebuild-writing/misc-files/patches/text.xml
index 05052e6..87b4a7e 100644
--- a/ebuild-writing/misc-files/patches/text.xml
+++ b/ebuild-writing/misc-files/patches/text.xml
@@ -112,6 +112,65 @@ from the <c>vim</c> patch tarball:
</body>
</section>
+<section>
+<title>Conditional patching</title>
+<body>
+
+<p>
+Patching is ideally only done to make the package in question build properly,
+and should not be done to modify the runtime behaviour of the package. This is
+what USE flags and features of the package are for. As such, it is preferable
to
+apply patches unconditionally and avoid conditional patching.
+</p>
+
+<p>
+There are a number of reasons to avoid conditional patching:
+</p>
+
+<ul>
+ <li>
+ It may go unnoticed that a patch fails to apply, if a package is not being
+ tested with a given flag
+ </li>
+ <li>
+ More variance is introduced and problems with a package can become much
more
+ difficult to debug
+ </li>
+ <li>
+ Patches should preferably be upstreamed, but conditional patches cannot
+ </li>
+</ul>
+
+<p>
+Consider the following example <c>src_prepare()</c> implementation:
+</p>
+
+<codesample lang="ebuild">
+src_prepare() {
+ if use threads; then
+ PATCHES+=( "${FILESDIR}"/${P}-mt.patch )
+ fi
+ default
+}
+</codesample>
+
+<p>
+As this patch is only applied when <c>USE="threads"</c> is set, any developer
+creating new versions of this package might not detect whether the patch
applies
+successfully if they don't test with the same flag.
+</p>
+
+<p>
+Although conditional patching is discouraged it can be unavoidable and as such,
+it is not considered a banned practice, but, to the extent possible, patches
+should be written such that they affect behaviour correctly based on e.g. build
+time definitions and configuration options rather than USE flags directly. This
+allows them to be applied unconditionally.
+</p>
+
+</body>
+</section>
+
<section>
<title>Clean Patch Howto</title>
<body>
