Patches

Why

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.

File Naming

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, because the patch may be used outside Gentoo.

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 behaviour
    • How to reproduce bug without 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 with 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 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):

PATCHES=(
	"${FILESDIR}"/${P}-dont-umask.patch #93671
)

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 <foo@cow.example.com>

Or when documenting relevant URLs, use something like:

Bug: https://upstream.example.com/12345
Bug: https://bugs.gentoo.org/9889

And if you want to note your copyright signoff, slap on a Signed-off-by tag:

Signed-off-by: Diligent Developer <larry@gentoo.org>

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. 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 @@) 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. That is, remove different leading backup/paths/ and .orig/.new suffixes. Your patch should be in the -p1 format because this tends to be much more standard than any other -p#. It is also what eapply understands by default. A good suggestion is to use either a/ and b/ (as in git format-patch) or the package name/version as the leading portion that gets stripped.

Also note that patch uses the timestamp info in order to remove empty files automatically. Alternatively, you can specify the -E option with eapply if you want to remove an empty file.

Removed lines should not appear in the patch because they are commented — just remove them entirely. Patches show removed lines by prefixing them with a -, 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.

The following function (for your interactive shell, not for the ebuild) will help deleting these things:

scrub_patch() {
	sed -i \
		-e '/^index /d' \
		-e '/^new file mode /d' \
		-e '/^Index:/d' \
		-e '/^=========/d' \
		-e '/^RCS file:/d' \
		-e '/^retrieving/d' \
		-e '/^diff/d' \
		-e '/^Files .* differ$/d' \
		-e '/^Only in /d' \
		-e '/^Common subdirectories/d' \
		-e '/^deleted file mode [0-9]*$/d' \
		-e '/^+++/s:\t.*::' \
		-e '/^---/s:\t.*::' \
		"$@"
}

scrub_patch some-patch-you-found.patch

Examples

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 diff command (timestamps, etc.).

Fixes compilation in FreeBSD.
https://bugs.gentoo.org/138123

--- man-1.6d/gencat/genlib.c
+++ man-1.6d/gencat/genlib.c
@@ -54,7 +54,7 @@
 #include <unistd.h>
 #endif

-#ifndef __linux__
+#if !defined(__linux__) && !defined(__FreeBSD__)
 #include <memory.h>
 static int bcopy(src, dst, length)
 char *src, *dst;

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
+++ mount/mount.c
@@ -1491,8 +1491,6 @@ main(int argc, char *argv[]) {
    if ((p = strrchr(progname, '/')) != NULL)
        progname = p+1;

-   umask(022);
-
    /* 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 */

Don't let target flags bleed into build flags.
Fix by Bertrand Jacquin.
https://bugs.gentoo.org/226035

--- netem/Makefile
+++ netem/Makefile
@@ -2,6 +2,7 @@ DISTGEN = maketable normal pareto paretonormal
 DISTDATA = normal.dist pareto.dist paretonormal.dist experimental.dist

 HOSTCC ?= $(CC)
+CCOPTS  = $(CBUILD_CFLAGS)
 LDLIBS += -lm

 all: $(DISTGEN) $(DISTDATA)