[pkgsrc/trunk]: pkgsrc/doc/guide/files components.xml: note some consideratio...

[gutteridge <gutteridge%pkgsrc.org@localhost>]

details:   https://anonhg.NetBSD.org/pkgsrc/rev/aed661cccaf1
branches:  trunk
changeset: 377011:aed661cccaf1
user:      gutteridge <gutteridge%pkgsrc.org@localhost>
date:      Fri Apr 15 13:47:57 2022 +0000

description:
components.xml: note some considerations when updating patches

diffstat:

 doc/guide/files/components.xml |  14 +++++++++++---
 1 files changed, 11 insertions(+), 3 deletions(-)

diffs (35 lines):

diff -r a53d6a738a90 -r aed661cccaf1 doc/guide/files/components.xml
--- a/doc/guide/files/components.xml    Fri Apr 15 12:43:32 2022 +0000
+++ b/doc/guide/files/components.xml    Fri Apr 15 13:47:57 2022 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: components.xml,v 1.61 2021/06/14 22:53:02 nia Exp $ -->
+<!-- $NetBSD: components.xml,v 1.62 2022/04/15 13:47:57 gutteridge Exp $ -->
 
 <chapter id="components"> <?dbhtml filename="components.html"?>
 <title>Package components - files, directories and contents</title>
@@ -285,8 +285,8 @@
 
   <para>For even more automation, we recommend using
   <command>mkpatches</command> from the same package to make a
-  whole set of patches. You just have to backup files before you
-  edit them to <filename>filename.orig</filename>, e.g. with
+  whole set of patches. You just have to back up files before you
+  edit them to <filename>filename.orig</filename>, e.g., with
   <command>cp -p filename filename.orig</command> or, easier, by
   using <command>pkgvi</command> again from the same package. If
   you upgrade a package this way, you can easily compare the new
@@ -316,6 +316,14 @@
   role="pkg">pkgtools/pkgdiff</filename> takes care of the name
   automatically.</para>
 
+  <para>When updating pre-existing patch files, if a file uses the old
+  <filename>patch-<replaceable>[a-z][a-z]</replaceable></filename>
+  convention, it's best not to change it to the new form, as that will
+  just cause churn that makes it harder to track changes to patching
+  over time. Similarly, if a patch now applies at different line offsets,
+  but still applies cleanly as-is, there's no need to update it, as that
+  also unnecessarily complicates the patch history.</para>
+
 </sect2>
 <sect2 id="components.patches.sources">
 <title>Sources where the patch files come from</title>