From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <gentoo-commits+bounces-1383015-garchives=archives.gentoo.org@lists.gentoo.org>
Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80])
(using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
key-exchange X25519 server-signature RSA-PSS (2048 bits))
(No client certificate requested)
by finch.gentoo.org (Postfix) with ESMTPS id B2CAE15808B
for <garchives@archives.gentoo.org>; Wed, 6 Apr 2022 18:41:17 +0000 (UTC)
Received: from pigeon.gentoo.org (localhost [127.0.0.1])
by pigeon.gentoo.org (Postfix) with SMTP id AD224E0BCB;
Wed, 6 Apr 2022 18:41:16 +0000 (UTC)
Received: from smtp.gentoo.org (woodpecker.gentoo.org [IPv6:2001:470:ea4a:1:5054:ff:fec7:86e4])
(using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256)
(No client certificate requested)
by pigeon.gentoo.org (Postfix) with ESMTPS id CAC3BE0BCB
for <gentoo-commits@lists.gentoo.org>; Wed, 6 Apr 2022 18:41:15 +0000 (UTC)
Received: from oystercatcher.gentoo.org (oystercatcher.gentoo.org [148.251.78.52])
(using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256)
(No client certificate requested)
by smtp.gentoo.org (Postfix) with ESMTPS id 61F83340F0B
for <gentoo-commits@lists.gentoo.org>; Wed, 6 Apr 2022 18:41:12 +0000 (UTC)
Received: from localhost.localdomain (localhost [IPv6:::1])
by oystercatcher.gentoo.org (Postfix) with ESMTP id BDBEA2A7
for <gentoo-commits@lists.gentoo.org>; Wed, 6 Apr 2022 18:41:10 +0000 (UTC)
From: "Ulrich Müller" <ulm@gentoo.org>
To: gentoo-commits@lists.gentoo.org
Content-Transfer-Encoding: 8bit
Content-type: text/plain; charset=UTF-8
Reply-To: gentoo-dev@lists.gentoo.org, "Ulrich Müller" <ulm@gentoo.org>
Message-ID: <1649270439.dcb57d688530aa1af4193aaec350d6d7f571c6cf.ulm@gentoo>
Subject: [gentoo-commits] proj/devmanual:master commit in: ebuild-writing/misc-files/patches/
X-VCS-Repository: proj/devmanual
X-VCS-Files: ebuild-writing/misc-files/patches/text.xml
X-VCS-Directories: ebuild-writing/misc-files/patches/
X-VCS-Committer: ulm
X-VCS-Committer-Name: Ulrich Müller
X-VCS-Revision: dcb57d688530aa1af4193aaec350d6d7f571c6cf
X-VCS-Branch: master
Date: Wed, 6 Apr 2022 18:41:10 +0000 (UTC)
Precedence: bulk
List-Post: <mailto:gentoo-commits@lists.gentoo.org>
List-Help: <mailto:gentoo-commits+help@lists.gentoo.org>
List-Unsubscribe: <mailto:gentoo-commits+unsubscribe@lists.gentoo.org>
List-Subscribe: <mailto:gentoo-commits+subscribe@lists.gentoo.org>
List-Id: Gentoo Linux mail <gentoo-commits.gentoo.org>
X-BeenThere: gentoo-commits@lists.gentoo.org
X-Auto-Response-Suppress: DR, RN, NRN, OOF, AutoReply
X-Archives-Salt: f5c00599-3adc-41eb-9d3a-9a0f035a0c97
X-Archives-Hash: 05711e2bfa1996ea1d7705a2376b8750
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>