git: be6e85b4a2 - main - [porters-handbook]: Clarify prefixes in patch file names

[Fernando Apesteguía]

The branch main has been updated by fernape:

URL: https://cgit.FreeBSD.org/doc/commit/?id=be6e85b4a2a66e6bd5a0b0cd5c9e6d24ff5247fc

commit be6e85b4a2a66e6bd5a0b0cd5c9e6d24ff5247fc
Author:     Fernando Apesteguía <fernape at FreeBSD.org>
AuthorDate: 2021-04-18 17:22:23 +0000
Commit:     Fernando Apesteguía <fernape at FreeBSD.org>
CommitDate: 2021-04-20 09:42:36 +0000

    [porters-handbook]: Clarify prefixes in patch file names
    
    Patches must start with `patch-` in order to be applied automatically.
    Conditional patches must not start with `patch-`.
    
    PR: 24903
    Reported by:    pauamma at gundo.com
    
    Approved by: 0mp (mentor)
    Differential Revision: https://reviews.freebsd.org/D28268
---
 .../content/en/books/porters-handbook/slow-porting/_index.adoc        | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/documentation/content/en/books/porters-handbook/slow-porting/_index.adoc b/documentation/content/en/books/porters-handbook/slow-porting/_index.adoc
index f40a105bac..4146408768 100644
--- a/documentation/content/en/books/porters-handbook/slow-porting/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/slow-porting/_index.adoc
@@ -132,6 +132,7 @@ Manual patch creation is usually not necessary. Automatic patch generation as de
 ====
 
 Patches are saved into files named [.filename]#patch-*# where * indicates the pathname of the file that is patched, such as [.filename]#patch-Imakefile# or [.filename]#patch-src-config.h#.
+Patches with file names which do not start with [.filename]#patch-# will not be applied automatically.
 
 After the file has been modified, man:diff[1] is used to record the differences between the original and the modified version. `-u` causes man:diff[1] to produce "unified" diffs, the preferred form.
 
@@ -208,6 +209,9 @@ DOS2UNIX_WRKSRC=	${WRKDIR}
 === Patching Conditionally
 
 Some ports need patches that are only applied for specific FreeBSD versions or when a particular option is enabled or disabled. Conditional patches are specified by placing the full paths to the patch files in `EXTRA_PATCHES`.
+Conditional patch file names usually start with [.filename]#extra-# although this is not necessary.
+However, their file names _must not_ start with [.filename]#patch-#.
+If they do, they are applied unconditionally by the framework which is undesired for conditional patches.
 
 [[slow-patch-extra-ex1]]
 .Applying a Patch for a Specific FreeBSD Version