From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <gentoo-commits+bounces-1785910-garchives=archives.gentoo.org@lists.gentoo.org>
Received: from smtp.gentoo.org (woodpecker.gentoo.org [140.211.166.183])
	(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 finch.gentoo.org (Postfix) with ESMTPS id 283571581B9
	for <garchives@archives.gentoo.org>; Sat, 20 Sep 2025 14:12:41 +0000 (UTC)
Received: from lists.gentoo.org (bobolink.gentoo.org [140.211.166.189])
	(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)
	(Authenticated sender: relay-lists.gentoo.org@gentoo.org)
	by smtp.gentoo.org (Postfix) with ESMTPSA id 12A9C341EA7
	for <garchives@archives.gentoo.org>; Sat, 20 Sep 2025 14:12:41 +0000 (UTC)
Received: from bobolink.gentoo.org (localhost [127.0.0.1])
	by bobolink.gentoo.org (Postfix) with ESMTP id F133C110573;
	Sat, 20 Sep 2025 14:12:39 +0000 (UTC)
Received: from smtp.gentoo.org (mail.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 bobolink.gentoo.org (Postfix) with ESMTPS id E5899110573
	for <gentoo-commits@lists.gentoo.org>; Sat, 20 Sep 2025 14:12:39 +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 993A5341EA7
	for <gentoo-commits@lists.gentoo.org>; Sat, 20 Sep 2025 14:12:39 +0000 (UTC)
Received: from localhost.localdomain (localhost [IPv6:::1])
	by oystercatcher.gentoo.org (Postfix) with ESMTP id E3F3C20FB
	for <gentoo-commits@lists.gentoo.org>; Sat, 20 Sep 2025 14:12:37 +0000 (UTC)
From: "Sam James" <sam@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, "Sam James" <sam@gentoo.org>
Message-ID: <1758377550.40944aae2d5e32d4a48b767bcf6d2a6d2851cc29.sam@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: sam
X-VCS-Committer-Name: Sam James
X-VCS-Revision: 40944aae2d5e32d4a48b767bcf6d2a6d2851cc29
X-VCS-Branch: master
Date: Sat, 20 Sep 2025 14:12:37 +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: 83bfb252-db77-4bdb-9912-f75843e24bab
X-Archives-Hash: cf71520b8ba5d88d0999dc9f9e51d86a

commit:     40944aae2d5e32d4a48b767bcf6d2a6d2851cc29
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Sat Sep 20 13:14:17 2025 +0000
Commit:     Sam James <sam <AT> gentoo <DOT> org>
CommitDate: Sat Sep 20 14:12:30 2025 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=40944aae

ebuild-writing/misc-files/patches: add simple 'Methods' section

It seems off to not have a brief mention of the two methods (eapply
and PATCHES) in our dedicated Patches file, so add some text to that end.

Signed-off-by: Sam James <sam <AT> gentoo.org>

 ebuild-writing/misc-files/patches/text.xml | 43 ++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/ebuild-writing/misc-files/patches/text.xml b/ebuild-writing/misc-files/patches/text.xml
index 5f17976..14b4fb9 100644
--- a/ebuild-writing/misc-files/patches/text.xml
+++ b/ebuild-writing/misc-files/patches/text.xml
@@ -53,6 +53,49 @@ up the tree too much.
 </p>
 </body>
 
+<section>
+<title>Methods</title>
+<body>
+<p>
+There are two ways to apply patches within an ebuild:
+</p>
+
+<ul>
+  <li>
+    <c>eapply</c> (function call)
+  </li>
+  <li>
+    <c>PATCHES</c> (array, usually global-scope): accepts both files as well as
+    directories of patches
+  </li>
+</ul>
+
+<p>
+<c>PATCHES</c> in global-scope is the primary style unless there's some
+complexity involved, like applying patches from a Debian 'series' file.
+</p>
+
+<codesample lang="ebuild" caption="An example of eapply">
+src_prepare() {
+	# Requires defining the src_prepare phase
+	default
+	eapply "${FILESDIR}"/foo-1.2.3-build-system.patch
+}
+</codesample>
+
+<codesample lang="ebuild" caption="An example of PATCHES">
+DEPEND="..."
+
+PATCHES=(
+	"${FILESDIR}"/foo-1.2.3-build-system.patch
+)
+
+# src_prepare automatically applies PATCHES in its default implementation
+</codesample>
+
+</body>
+</section>
+
 <section>
 <title>Patch descriptions</title>
 <body>