[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/misc-files/patches/

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/misc-files/patches/

[Markos Chandras]

commit:     1c5e08e0ebc612ce3745ea25ac652ebdd1302565
Author:     mudler <mudler <AT> dark-lab <DOT> net>
AuthorDate: Wed Jul 23 11:08:45 2014 +0000
Commit:     Markos Chandras <hwoarang <AT> gentoo <DOT> org>
CommitDate: Wed Jul 23 11:08:45 2014 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/devmanual.git;a=commit;h=1c5e08e0

fixing a small typo in ebuild-writing/misc-files/patches

---
 ebuild-writing/misc-files/patches/text.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ebuild-writing/misc-files/patches/text.xml b/ebuild-writing/misc-files/patches/text.xml
index 3704f71..0be488c 100644
--- a/ebuild-writing/misc-files/patches/text.xml
+++ b/ebuild-writing/misc-files/patches/text.xml
@@ -114,7 +114,7 @@ doing:
 </p>
 
 <pre>
-cvs add -ko files/${P}-the-cool-patch.path
+cvs add -ko files/${P}-the-cool-patch.patch
 </pre>
 
 <p>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/misc-files/patches/

[Markos Chandras]

commit:     1c5e08e0ebc612ce3745ea25ac652ebdd1302565
Author:     mudler <mudler <AT> dark-lab <DOT> net>
AuthorDate: Wed Jul 23 11:08:45 2014 +0000
Commit:     Markos Chandras <hwoarang <AT> gentoo <DOT> org>
CommitDate: Wed Jul 23 11:08:45 2014 +0000
URL:        http://sources.gentoo.org/gitweb/?p=proj/devmanual.git;a=commit;h=1c5e08e0

fixing a small typo in ebuild-writing/misc-files/patches

---
 ebuild-writing/misc-files/patches/text.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ebuild-writing/misc-files/patches/text.xml b/ebuild-writing/misc-files/patches/text.xml
index 3704f71..0be488c 100644
--- a/ebuild-writing/misc-files/patches/text.xml
+++ b/ebuild-writing/misc-files/patches/text.xml
@@ -114,7 +114,7 @@ doing:
 </p>
 
 <pre>
-cvs add -ko files/${P}-the-cool-patch.path
+cvs add -ko files/${P}-the-cool-patch.patch
 </pre>
 
 <p>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/misc-files/patches/

[Justin Lecher]

commit:     8fdfbd22b2c3b2863d351ec97322c06cbd29e2ba
Author:     Johannes Huber <johu <AT> gentoo <DOT> org>
AuthorDate: Thu Aug 20 09:15:06 2015 +0000
Commit:     Justin Lecher <jlec <AT> gentoo <DOT> org>
CommitDate: Thu Aug 20 09:15:06 2015 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=8fdfbd22

Update patches

Due to git migration.

 ebuild-writing/misc-files/patches/text.xml | 16 ++++++----------
 1 file changed, 6 insertions(+), 10 deletions(-)

diff --git a/ebuild-writing/misc-files/patches/text.xml b/ebuild-writing/misc-files/patches/text.xml
index 0be488c..cd85244 100644
--- a/ebuild-writing/misc-files/patches/text.xml
+++ b/ebuild-writing/misc-files/patches/text.xml
@@ -18,7 +18,7 @@ is conventional. Patches are best named <c>${P}-what-it-does.patch</c> (or
 description of what the patch is for. If the patch is to fix a
 specific bug, it is often useful to add in the bug number <d/> for
 example, <c>vim-7.0-cron-vars-79981.patch</c>. If the patch is pulled from
-upstream's CVS / SVN repository, it can help to include the revision
+upstream's VCS repository, it can help to include the revision
 number in the patch name as a suffix to the version part <d/>
 <c>fluxbox-0.9.12-3860-menu-backups.patch</c>.
 </p>
@@ -57,7 +57,7 @@ later. Good things to include in comments are:
     What the patch actually does. Bug numbers are good here.
   </li>
   <li>
-    Where the patch came from. Is it an upstream CVS/SVN pull,
+    Where the patch came from. Is it an upstream VCS pull,
     something from Bugzilla, something you wrote?
   </li>
   <li>
@@ -107,20 +107,16 @@ from the <c>vim</c> patch tarball:
 
 <p>
 When adding a patch to the tree be sure to check that the patch doesn't have
-CVS keywords in it that will be expanded (such as <c>$Id$</c>).  If the patch
+Git keywords in it that will be expanded (such as <c>$Id$</c>).  If the patch
 contains these, it will break manifests unless you add it to the tree
-correctly.  In the case that it does have the keywords, you should add it by
-doing:
+correctly.  In the case that it does have the keywords, you should remove them.
+Afterwards they can be added like every other file:
 </p>
 
 <pre>
-cvs add -ko files/${P}-the-cool-patch.patch
+git add files/${P}-the-cool-patch.patch
 </pre>
 
-<p>
-<c>-ko</c> disables keyword expansion for that specific file.  If it doesn't
-have keywords in it, then you can add it normally without the extra argument.
-</p>
 </body>
 </section>
 </body>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/misc-files/patches/

[Göktürk Yüksek]

commit:     68856e335f66b04722536a899c53459246064174
Author:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
AuthorDate: Mon Jun 13 15:52:25 2016 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Thu Jun 16 01:16:13 2016 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=68856e33

ebuild-writing/misc-files/patches: suggest compressing patches with xz

With app-arch/xz-utils being in @system, suggest patches to be
compressed with xz as it achieves higher compression rates than bzip2.

Reported-by: dracwyrm <j.scruggs <AT> gmail.com>

 ebuild-writing/misc-files/patches/text.xml | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/ebuild-writing/misc-files/patches/text.xml b/ebuild-writing/misc-files/patches/text.xml
index 4bb8375..f0b1f13 100644
--- a/ebuild-writing/misc-files/patches/text.xml
+++ b/ebuild-writing/misc-files/patches/text.xml
@@ -24,12 +24,13 @@ number in the patch name as a suffix to the version part <d/>
 </p>
 
 <p>
-Larger patches should be <uri link="::general-concepts/mirrors/#suitable-download-hosts">mirrored</uri>,
-preferrable on the Gentoo Infrastructure. When mirroring patches, choosing a
-name that will not cause conflicts is important — the <c>${P}</c>
-prefix is highly recommended here. Mirrored patches are often
-compressed with <c>bzip2</c>. Remember to list these patches in
-<c>SRC_URI</c>.
+Larger patches should be
+<uri link="::general-concepts/mirrors/#suitable-download-hosts">
+mirrored</uri>, preferably on the Gentoo Infrastructure. When
+mirroring patches, choosing a name that will not cause conflicts is
+important — the <c>${P}</c> prefix is highly recommended
+here. Mirrored patches are often compressed with <c>xz</c> or
+<c>bzip2</c>. Remember to list these patches in <c>SRC_URI</c>.
 </p>
 
 <note>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/misc-files/patches/

[Ulrich Müller]

commit:     b50b1ad173ee9ea066231289a5b9f5ee644acfcc
Author:     Mikle Kolyada <zlogene <AT> gentoo <DOT> org>
AuthorDate: Fri Jun 15 22:54:15 2018 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Fri Jun 22 18:39:31 2018 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=b50b1ad1

ebuild-writing/../patches: add warning about strip

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

diff --git a/ebuild-writing/misc-files/patches/text.xml b/ebuild-writing/misc-files/patches/text.xml
index 506871f..fe9f471 100644
--- a/ebuild-writing/misc-files/patches/text.xml
+++ b/ebuild-writing/misc-files/patches/text.xml
@@ -37,6 +37,13 @@ here. Mirrored patches are often compressed with <c>xz</c> or
 Patches included in <c>${FILESDIR}</c> should never be compressed.
 </note>
 
+<warning>
+Starting from EAPI=6 a strip patch level was limited to the <c>-p1</c>.
+Although it can be overridden with a <c>eapply -p&lt;strip_level&gt;</c>
+command, it is higly recommended to adapt the patch itself to work
+with the <c>-p1</c> default.
+</warning>
+
 <p>
 If a package requires many patches, even if they are individually
 small, it is often best to create a patch tarball to avoid cluttering

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/misc-files/patches/

[Ulrich Müller]

commit:     8ffb4ecb220c9126a9a57ac3d2591a2604cdd438
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Tue Feb 16 19:31:37 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sat Feb 20 07:54:02 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=8ffb4ecb

ebuild-writing/misc-files/patches: Convert to DevBook XML markup

- Start sentences with uppercase letters
- Change some sentences from first-person to third-person
- Less informal/colloquial style
- Modernise the text a little (e.g., eapply instead of epatch)
- Be more in line with GLEP 66 (e.g., "Bug" instead of "Gentoo-Bug-URL")

Closes: https://bugs.gentoo.org/247266
Closes: https://github.com/gentoo/devmanual/pull/192
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 ebuild-writing/misc-files/patches/text.xml | 337 +++++++++++++++++------------
 1 file changed, 200 insertions(+), 137 deletions(-)

diff --git a/ebuild-writing/misc-files/patches/text.xml b/ebuild-writing/misc-files/patches/text.xml
index 21e6ef8..62b8a04 100644
--- a/ebuild-writing/misc-files/patches/text.xml
+++ b/ebuild-writing/misc-files/patches/text.xml
@@ -114,123 +114,189 @@ from the <c>vim</c> patch tarball:
 <title>Clean Patch Howto</title>
 <body>
 
+<p>
+"Clean patch" does not refer to the patch itself (as in the changes it makes to
+the source code). It refers to all the metadata that exists in the patch to
+make it "maintainable".
+</p>
+
+</body>
+
+<subsection>
+<title>Why</title>
+<body>
+
+<p>
+This may take more effort "up front", but the amount of effort that it saves
+for everyone else in the future more than makes up for it. This refers to other
+distributions or upstream maintainers who read the patch, or future Gentoo
+maintainers. By keeping all patches "clean", people can quickly and easily
+assess a patch without searching through many other files.
+</p>
+
+</body>
+</subsection>
+
+<subsection>
+<title>File Naming</title>
+<body>
+
+<p>
+Your patch name should be short and to the point. When doing a file listing
+(e.g., <c>ls files/</c>), it's a lot easier to be able to scan for relevant
+patches when they have good keywords in their file names.
+</p>
+
+<p>
+It should also include the package name and the version it was written against.
+This way, people searching for patches or who happen to just stumble across the
+file itself have a clue as to what it's for. Stripping out the <c>${PN}</c>
+(and to a lesser extent, the <c>${PV}</c>) makes the filename significantly
+less useful. The fact the files are typically stored in
+<c>${CATEGORY}/${PN}/files/</c> is irrelevant, because the patch may be used
+outside Gentoo.
+</p>
+
+</body>
+</subsection>
+
+<subsection>
+<title>How</title>
+<body>
+
+<p>
+Here's a check list of things to keep in the patch header:
+</p>
+
+<ul>
+  <li>
+    External references
+    <ul>
+      <li>Upstream mailing archives</li>
+      <li>Upstream bug reports</li>
+      <li>Upstream commit links</li>
+      <li>Upstream ChangeLog entries</li>
+      <li>Gentoo bug reports</li>
+    </ul>
+  </li>
+  <li>
+    Short/medium explanation
+    <ul>
+      <li>Why is the patch needed?</li>
+      <li>What is it fixing?</li>
+      <li>Why is it fixing it the way it is?</li>
+      <li>Proposal for better fixes in the future?</li>
+      <li>Is it a stop gap measure (workaround)?</li>
+      <li>How was it regression tested?</li>
+      <li>
+        Examples of before/after behaviour
+        <ul>
+          <li>How to reproduce bug without patch</li>
+          <li>How to show bug is fixed after patch</li>
+          <li>
+            Maybe upstream fixed it in a different way, so this test can be
+            used to show that the patch is no longer needed with newer versions
+          </li>
+        </ul>
+      </li>
+    </ul>
+  </li>
+  <li>
+    Status
+    <ul>
+      <li>Was it merged/rejected/postponed/etc. upstream?</li>
+      <li>Is it distribution-specific?</li>
+    </ul>
+  </li>
+  <li>
+    Attribution
+    <ul>
+      <li>Who found the bug?</li>
+      <li>Who fixed the bug?</li>
+      <li>Who wrote the patch?</li>
+      <li>Who tested the patch?</li>
+      <li>Who gave advice on the patch?</li>
+    </ul>
+  </li>
+</ul>
+
+<p>
+All this information should be <e>in the patch itself</e>. It should never be
+found in something like the ebuild. If you really want to put a comment next
+to a patch in an ebuild, then this is about the only thing that is OK
+(where 93671 is the Gentoo bug number):
+</p>
+
+<codesample lang="ebuild">
+PATCHES=(
+	"${FILESDIR}"/${P}-dont-umask.patch #93671
+)
+</codesample>
+
+<p>
+When documenting these things, it might be useful to use RFC822/Git-style tags
+to format the metadata. So when documenting the author, use:
+</p>
+
+<pre>
+From: Nice Person &lt;foo@cow.example.com&gt;
+</pre>
+
+<p>
+Or when documenting relevant URLs, use something like:
+</p>
+
+<pre>
+Bug: https://upstream.example.com/12345
+Bug: https://bugs.gentoo.org/9889
+</pre>
+
+<p>
+And if you want to note your copyright signoff, slap on a Signed-off-by tag:
+</p>
+
+<pre>
+Signed-off-by: Diligent Developer &lt;larry@gentoo.org&gt;
+</pre>
+
+<p>
+Finally, your patch should be clear of useless cruft. If it was not taken
+straight from an upstream SCM (<c>git format-patch</c> or <c>svn diff -r #</c>
+or <c>cvs diff -r 1.123 -r 1.124</c>), then the metadata is useless. So delete
+it. This refers to things like the diff command used to produce the patch,
+or the timestamps on the files, local revision info, or other similar spam.
+Note that the context info (the stuff that comes after the <c>@@</c>) should
+be left, as that can be invaluable when applying patches to later versions.
+For example:
+</p>
+
 <pre>
----------------------
-  CLEAN PATCH HOWTO
----------------------
-
-when i say "clean patch", i am not referring to the patch itself (as in the
-changes it makes to the source code).  i am referring to all the metadata that
-exists in the patch to make it "maintainable".
-
--------
-  WHY
--------
-
-you might be thinking "wow, this looks like effort".  well you best shut your
-brain hole and do it anyways.  seriously though ...
-
-this may take more effort "up front", but the amount of effort that it saves
-for everyone else in the future more than makes up for it.  i refer to other
-distributions or upstream maintainers that read the patch.  or future Gentoo
-maintainers / developers.  too many hours have i spent staring at a patch
-(whether it be long or tiny) with no documentation and no references as to why
-the changes it is making to a package exist at all.  by keeping all patches
-"clean", people can quickly and easily assess a patch without searching through
-a metric butt ton of other files.
-
-so make your patch clean in the first place and stop screwing others in ways
-they do not enjoy.  stick with the pleasant methods please.
-
----------------
-  FILE NAMING
----------------
-
-this is quick to do, so let's get it out of the way.  your patch name should be
-short and to the point.  when doing a file listing (e.g. `ls files/`), it's a
-lot easier to be able to scan for relevant patches when they have good keywords
-in their file names.
-
-it should also include the package name and the version it was written against.
-this way people searching for patches or who happen to just stumble across the
-file itself have a clue as to what it's for.  stripping out the $PN (and to a
-lesser extent, the $PV) makes the filename significantly less useful.  the fact
-the files are typically stored in $CATEGORY/$PN/files/ is irrelevant.  we're
-trying to think beyond the Gentoo box here.
-
-it's also more consistent.  consistency matters as minor/pointless deviations
-only serve to slow people down.
-
--------
-  HOW
--------
-
-here's a check list of things to keep in the patch header:
- - external references
-	- upstream mailing archives
-	- upstream bug reports
-	- upstream commit links
-	- upstream changelog entries
-	- Gentoo bug reports
- - short / medium explanation
-	- why is the patch needed ?
-	- what is it fixing ?
-	- why is it fixing it the way it is ?
-	- proposal for better fixes in the future ?
-	- is it a stop gap measure (workaround) ?
-	- how was it regression tested ?
-	- examples of before / after behavior
-		- how to reproduce bug w/out patch
-		- how to show bug is fixed after patch
-		- maybe upstream fixed it in a different way, so this test can be
-		  used to show that the patch is no longer needed w/newer versions
- - status
-	- was it merged/rejected/postponed/etc... upstream ?
-	- is it distribution-specific ?
- - attribution
-	- who found the bug ?
-	- who fixed the bug ?
-	- who wrote the patch ?
-	- who tested the patch ?
-	- who gave advice on the patch ?
-
-all this information should be *in the patch itself*.  it should never ever be
-found in something like the ebuild.  if you really really want to put a comment
-next to a patch in an ebuild, then this is about the only thing that is OK:
-	epatch "${FILESDIR}"/${P}-fatty-cow.patch #12345
-(where 12345 is the Gentoo bug #)
-
-when documenting these things, it might be useful to use RFC822/git style tags
-to format the metadata.  so when documenting the author, use:
-	From: Nice Person &lt;foo@cow.com&gt;
-or when documenting relevant urls, use something like:
-	Project-Bug-URL: http://upstream.tracker.com/12345
-	Gentoo-Bug-URL: http://bugs.gentoo.org/9889
-and if you want to note your approval, slap on a s-o-b tag:
-	Signed-off-by: Diligent Developer &lt;funky-cow-butt@gentoo.org&gt;
-
-finally, your patch should be clear of useless cruft.  if it was not taken
-straight from an upstream SCM (`git format-patch` or `svn diff -r #` or
-`cvs diff -r 1.123 -r 1.124`), then the metadata is useless.  so delete it.
-i'm referring to things like the diff command used to produce the patch, or the
-timestamps on the files, local revision info, or other similar spam. note that
-the context info (the stuff that comes after the @@) should be left as that can
-be invaluable when applying patches to later versions.  for example:
 @@ -80,6 +82,7 @@ case $sys in
                   ^^^^^^^^^^^^ keep this part
-extra points if you make the filename in the ---/+++ section consistent and
-sane.  i.e. remove different leading backup/paths/ and .orig/.new suffixes.
-extra extra points if your patch is in the -p1 format.  this tends to be much
-more standard than any other -p#.  a good suggestion is to use the package
-name / version as the leading portion that gets stripped.
-
-also note that while `patch` uses the timestamp info in order to remove empty
-files automatically, in Gentoo, we apply all patches with -E, so the timestamp
-info does not matter.  if you really want to keep an empty file around though,
-just replace the file with a comment or an empty line or ...
-
-if deleting these things yourself sounds like the kind of fun that involves
-nipple clamps and electricity, try this:
+</pre>
+
+<p>
+Extra points if you make the filename in the <c>---</c>/<c>+++</c> section
+consistent and sane. That is, remove different leading <c>backup/paths/</c>
+and <c>.orig</c>/<c>.new</c> suffixes. Your patch should be in the <c>-p1</c>
+format because this tends to be much more standard than any other <c>-p#</c>.
+It is also what <c>eapply</c> understands by default. A good suggestion is to
+use either <c>a/</c> and <c>b/</c> (as in <c>git format-patch</c>) or the
+package name/version as the leading portion that gets stripped.
+</p>
+
+<p>
+Also note that <c>patch</c> uses the timestamp info in order to remove empty
+files automatically. Alternatively, you can specify the <c>-E</c> option with
+<c>eapply</c> if you want to remove an empty file.
+</p>
+
+<p>
+The following function (for your interactive shell, not for the ebuild) will
+help deleting these things:
+</p>
+
+<codesample lang="ebuild">
 scrub_patch() {
 	sed -i \
 		-e '/^index /d' \
@@ -248,22 +314,26 @@ scrub_patch() {
 		-e '/^---/s:\t.*::' \
 		"$@"
 }
+
 scrub_patch some-patch-you-found.patch
+</codesample>
 
-some more info can be found here:
-http://devmanual.gentoo.org/ebuild-writing/misc-files/patches/index.html
+</body>
+</subsection>
 
------------
-  EXAMPLE
------------
+<subsection>
+<title>Examples</title>
+<body>
 
-here we see a simple explanation and a URL for more info (this patch could do
-with some attribution however ...).  no metadata exists from running the `diff`
-command (timestamps, etc...).
-&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt; man-1.6d-fbsd.patch &gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;
-Fixes compilation in FreeBSD.
+<p>
+This shows a simple explanation and a URL for more info (this patch could do
+with some attribution however). No metadata exists from running the <c>diff</c>
+command (timestamps, etc.).
+</p>
 
-http://bugs.gentoo.org/138123
+<pre><!-- man-1.6d-fbsd.patch -->
+Fixes compilation in FreeBSD.
+https://bugs.gentoo.org/138123
 
 --- man-1.6d/gencat/genlib.c
 +++ man-1.6d/gencat/genlib.c
@@ -276,15 +346,11 @@ http://bugs.gentoo.org/138123
  #include &lt;memory.h&gt;
  static int bcopy(src, dst, length)
  char *src, *dst;
+</pre>
 
-&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt; man-1.6d-fbsd.patch &gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;
-
-
-&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt; util-linux-2.12q-dont-umask.patch &gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;
+<pre><!-- util-linux-2.12q-dont-umask.patch -->
 Don't force umask to 022 or the -o umask option doesn't work.
-
 Patch by Daniel Drake.
-
 https://bugs.gentoo.org/93671
 
 --- mount/mount.c
@@ -298,14 +364,11 @@ https://bugs.gentoo.org/93671
     /* People report that a mount called from init without console
        writes error messages to /etc/mtab
        Let us try to avoid getting fd's 0,1,2 */
-&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt; util-linux-2.12q-dont-umask.patch &gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;
-
+</pre>
 
-&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt; iproute2-2.6.25.20080417-build.patch &gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;
+<pre><!-- iproute2-2.6.25.20080417-build.patch -->
 Don't let target flags bleed into build flags.
-
 Fix by Bertrand Jacquin.
-
 https://bugs.gentoo.org/226035
 
 --- netem/Makefile
@@ -318,10 +381,10 @@ https://bugs.gentoo.org/226035
  LDLIBS += -lm
 
  all: $(DISTGEN) $(DISTDATA)
-&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt;&lt; iproute2-2.6.25.20080417-build.patch &gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;
 </pre>
 
 </body>
+</subsection>
 </section>
 </chapter>
 </guide>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/misc-files/patches/

[Ulrich Müller]

commit:     813cdcb601e249093826da01806bad5f81aff3f3
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Mon Feb 22 16:50:34 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Mon Feb 22 16:50:34 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=813cdcb6

ebuild-writing/misc-files/patches: Typo

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 ebuild-writing/misc-files/patches/text.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ebuild-writing/misc-files/patches/text.xml b/ebuild-writing/misc-files/patches/text.xml
index 62b8a04..91afd33 100644
--- a/ebuild-writing/misc-files/patches/text.xml
+++ b/ebuild-writing/misc-files/patches/text.xml
@@ -40,7 +40,7 @@ Patches included in <c>${FILESDIR}</c> should never be compressed.
 <warning>
 Starting from EAPI=6 a strip patch level was limited to the <c>-p1</c>.
 Although it can be overridden with a <c>eapply -p&lt;strip_level&gt;</c>
-command, it is higly recommended to adapt the patch itself to work
+command, it is highly recommended to adapt the patch itself to work
 with the <c>-p1</c> default.
 </warning>
 

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/misc-files/patches/

[Ulrich Müller]

commit:     625eed727aff1a87e17e2585b498a650acbce22e
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Sun Mar 21 02:25:29 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Apr  7 17:28:13 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=625eed72

ebuild-writing/misc-files/patches: slight phrasing tweak re patch source

Signed-off-by: Sam James <sam <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

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

diff --git a/ebuild-writing/misc-files/patches/text.xml b/ebuild-writing/misc-files/patches/text.xml
index 83d936f..ea9d607 100644
--- a/ebuild-writing/misc-files/patches/text.xml
+++ b/ebuild-writing/misc-files/patches/text.xml
@@ -66,8 +66,8 @@ later. Good things to include in comments are:
     What the patch actually does. Bug numbers are good here.
   </li>
   <li>
-    Where the patch came from. Is it an upstream VCS pull,
-    something from Bugzilla, something you wrote?
+    Where the patch came from. For example, is it from an upstream VCS,
+    something from Bugzilla, or something you wrote?
   </li>
   <li>
     Whether the patch has been sent upstream, if applicable.

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/misc-files/patches/

[Ulrich Müller]

commit:     c7d05225d1a25f8d01e934125953d2990cccabb1
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Sun Mar 21 02:24:25 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Apr  7 17:28:12 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=c7d05225

ebuild-writing/misc-files/patches: grammatical fix re patch strip level

Signed-off-by: Sam James <sam <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 ebuild-writing/misc-files/patches/text.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ebuild-writing/misc-files/patches/text.xml b/ebuild-writing/misc-files/patches/text.xml
index 91afd33..83d936f 100644
--- a/ebuild-writing/misc-files/patches/text.xml
+++ b/ebuild-writing/misc-files/patches/text.xml
@@ -38,7 +38,7 @@ Patches included in <c>${FILESDIR}</c> should never be compressed.
 </note>
 
 <warning>
-Starting from EAPI=6 a strip patch level was limited to the <c>-p1</c>.
+Starting from EAPI=6, the patch strip level defaults to <c>-p1</c>.
 Although it can be overridden with a <c>eapply -p&lt;strip_level&gt;</c>
 command, it is highly recommended to adapt the patch itself to work
 with the <c>-p1</c> default.

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/misc-files/patches/

[Ulrich Müller]

commit:     0882c4ee932d075beb3f08ead4da97043ffcdcb5
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Sun Mar 21 04:48:17 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Wed Apr  7 17:28:17 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=0882c4ee

ebuild-writing/misc-files/patches: add reference to ${FILESDIR} in other section

Signed-off-by: Sam James <sam <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

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

diff --git a/ebuild-writing/misc-files/patches/text.xml b/ebuild-writing/misc-files/patches/text.xml
index ea9d607..7d13588 100644
--- a/ebuild-writing/misc-files/patches/text.xml
+++ b/ebuild-writing/misc-files/patches/text.xml
@@ -30,7 +30,9 @@ mirrored</uri>, preferably on the Gentoo Infrastructure. When
 mirroring patches, choosing a name that will not cause conflicts is
 important — the <c>${P}</c> prefix is highly recommended
 here. Mirrored patches are often compressed with <c>xz</c> or
-<c>bzip2</c>. Remember to list these patches in <c>SRC_URI</c>.
+<c>bzip2</c>. Remember to list these patches in <c>SRC_URI</c>. Please
+see <uri link="::ebuild-maintenance/new-ebuild/#The files Directory"/>
+for more information.
 </p>
 
 <note>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/misc-files/patches/

[Ulrich Müller]

commit:     ec24130fc17c4d48574721aeace1493eb25e7dea
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Sat Apr 10 00:13:22 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Fri Jun 18 06:11:32 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=ec24130f

ebuild-writing/misc-files/patches: modernise patch example

* Drop dates as we now recommend
* Use patch level 1

Signed-off-by: Sam James <sam <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

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

diff --git a/ebuild-writing/misc-files/patches/text.xml b/ebuild-writing/misc-files/patches/text.xml
index 7d13588..8d54dfd 100644
--- a/ebuild-writing/misc-files/patches/text.xml
+++ b/ebuild-writing/misc-files/patches/text.xml
@@ -96,8 +96,8 @@ from the <c>vim</c> patch tarball:
 <pre>
 # Detect Gentoo apache files properly. Gentoo bug 83565.
 
---- runtime/filetype.vim.orig   2005-03-25 01:44:12.000000000 +0000
-+++ runtime/filetype.vim        2005-03-25 01:45:15.000000000 +0000
+--- a/runtime/filetype.vim
++++ b/runtime/filetype.vim
 @@ -93,6 +93,9 @@
  " Gentoo apache config file locations (Gentoo bug #76713)
  au BufNewFile,BufRead /etc/apache2/conf/*/* setf apache

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/misc-files/patches/

[Ulrich Müller]

commit:     39680e44ae7267f09465cef26f156195e55e6483
Author:     Sam James <sam <AT> gentoo <DOT> org>
AuthorDate: Sat Apr 10 00:15:09 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Fri Jun 18 06:12:36 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=39680e44

ebuild-writing/misc-files/patches: discourage adding comments within patch

We shouldn't add comments (#) within patch changes to source code
(etc) because it's unnecessary noise. Comments *at the top* of the
patch are, of course, welcoome.

Closes: https://github.com/gentoo/devmanual/pull/217
Signed-off-by: Sam James <sam <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

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

diff --git a/ebuild-writing/misc-files/patches/text.xml b/ebuild-writing/misc-files/patches/text.xml
index 8d54dfd..05052e6 100644
--- a/ebuild-writing/misc-files/patches/text.xml
+++ b/ebuild-writing/misc-files/patches/text.xml
@@ -293,6 +293,14 @@ files automatically. Alternatively, you can specify the <c>-E</c> option with
 <c>eapply</c> if you want to remove an empty file.
 </p>
 
+<p>
+Removed lines should not appear in the patch because they are commented <d/>
+just remove them entirely. Patches show removed lines by prefixing them with
+a <c>-</c>, so no information is lost by simply deleting lines rather than
+commenting them out (which adds noise). This makes the patch shorter and
+more readable.
+</p>
+
 <p>
 The following function (for your interactive shell, not for the ebuild) will
 help deleting these things:

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/misc-files/patches/

[Ulrich Müller]

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>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/misc-files/patches/

[Ulrich Müller]

commit:     5196ecf9214c74aec620b0b0580e6264083a184a
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Mon Apr 29 16:19:17 2024 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue May  7 17:16:52 2024 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=5196ecf9

ebuild-writing/misc-files/patches: Revert wording change

This is referred to as the "Clean patch howto" from several other
places. The wording change would also break links because the section
title is used as fragment identifier.

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 ebuild-writing/misc-files/patches/text.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ebuild-writing/misc-files/patches/text.xml b/ebuild-writing/misc-files/patches/text.xml
index c71551b..239fd1b 100644
--- a/ebuild-writing/misc-files/patches/text.xml
+++ b/ebuild-writing/misc-files/patches/text.xml
@@ -172,7 +172,7 @@ allows them to be applied unconditionally.
 </section>
 
 <section>
-<title>Clean patch guide</title>
+<title>Clean patch howto</title>
 <body>
 
 <p>