commit: 6613e9d82f910d77616f15d916ab3d3596f91399 Author: Ulrich Müller <ulm <AT> gentoo <DOT> org> AuthorDate: Tue Feb 16 19:27:36 2021 +0000 Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org> CommitDate: Sat Feb 20 07:53:57 2021 +0000 URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=6613e9d8
ebuild-writing/misc-files/patches: Add section about clean patches Taken from https://dev.gentoo.org/~vapier/clean-patches (verbatim, except for escaping reserved characters). Original-Author: Mike Frysinger <vapier <AT> gentoo.org> Bug: https://bugs.gentoo.org/247266 Signed-off-by: Mike Frysinger <vapier <AT> gentoo.org> Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org> appendices/contributors/text.xml | 3 + ebuild-writing/misc-files/patches/text.xml | 214 +++++++++++++++++++++++++++++ 2 files changed, 217 insertions(+) diff --git a/appendices/contributors/text.xml b/appendices/contributors/text.xml index d822dfa..e80dbcb 100644 --- a/appendices/contributors/text.xml +++ b/appendices/contributors/text.xml @@ -122,6 +122,9 @@ Misc <author name="Lucas Ramage" email="[email protected]"> Search functionality </author> +<author name="Mike Frysinger" email="[email protected]"> + <uri link="::ebuild-writing/misc-files/patches/#Clean Patch Howto"/> +</author> </authors> </body> diff --git a/ebuild-writing/misc-files/patches/text.xml b/ebuild-writing/misc-files/patches/text.xml index 87cc328..21e6ef8 100644 --- a/ebuild-writing/misc-files/patches/text.xml +++ b/ebuild-writing/misc-files/patches/text.xml @@ -107,6 +107,220 @@ from the <c>vim</c> patch tarball: au BufNewFile,BufRead *.a65 setf a65 </pre> +</body> +</section> + +<section> +<title>Clean Patch Howto</title> +<body> + +<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 <[email protected]> +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 <[email protected]> + +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: +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 + +some more info can be found here: +http://devmanual.gentoo.org/ebuild-writing/misc-files/patches/index.html + +----------- + EXAMPLE +----------- + +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...). +<<<<<<<<<<<<<<<<<<<<<<<<<<<<< man-1.6d-fbsd.patch >>>>>>>>>>>>>>>>>>>>>>>>>>>>> +Fixes compilation in FreeBSD. + +http://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; + +<<<<<<<<<<<<<<<<<<<<<<<<<<<<< man-1.6d-fbsd.patch >>>>>>>>>>>>>>>>>>>>>>>>>>>>> + + +<<<<<<<<<<<<<<<<<<<<<< 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 ++++ 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 */ +<<<<<<<<<<<<<<<<<<<<<< util-linux-2.12q-dont-umask.patch >>>>>>>>>>>>>>>>>>>>>> + + +<<<<<<<<<<<<<<<<<<<< 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 ++++ 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) +<<<<<<<<<<<<<<<<<<<< iproute2-2.6.25.20080417-build.patch >>>>>>>>>>>>>>>>>>>>> +</pre> + </body> </section> </chapter>
