| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-Id: <5114385ce1897015ad96f59f0fd46014d5f07786.1369312746.git.PuZZleDucK@gmail.com>
Date: Thu, 23 May 2013 22:49:53 +1000
From: Ben Minerds <puzzleduck@...il.com>
To: greg@...ah.com, rob@...dley.net
Cc: Ben Minerds <PuZZleDucK@...il.com>, linux-doc@...r.kernel.org,
linux-kernel@...r.kernel.org
Subject: [PATCH 1/8] Documentation: Adding "The Perfect Patch" by Andrew Morton
Adding Andrews advice on patch submission and subdirectory for further patch
documentstion.
Signed-off-by: Ben Minerds <puzzleduck@...il.com>
---
.../patches/The-Perfect-Patch.txt | 167 +++++++++++++++++++++
1 file changed, 167 insertions(+)
create mode 100644 Documentation/development-process/patches/The-Perfect-Patch.txt
diff --git a/Documentation/development-process/patches/The-Perfect-Patch.txt b/Documentation/development-process/patches/The-Perfect-Patch.txt
new file mode 100644
index 0000000..b07074e
--- /dev/null
+++ b/Documentation/development-process/patches/The-Perfect-Patch.txt
@@ -0,0 +1,167 @@
+From: Andrew Morton [email blocked]
+To: Mukker, Atul [email blocked]
+Subject: Re: [patch] 2.6.9-rc1-mm1: megaraid_mbox.c compile error with gcc 3.4
+Date: Sat, 28 Aug 2004 13:04:19 -0700
+
+"Mukker, Atul" [email blocked] wrote:
+>
+> The driver and the patches with the re-ordered functions is available at
+> ftp://ftp.lsil.com/pub/linux-megaraid/drivers/version-2.20.3.1/
+
+I dunno about James, but I *really* dislike receiving patches by going and
+getting them from internet servers. It breaks our commonly-used tools. It
+loses authorship info. It loses Signed-off-by: info. There is no
+changelog. All this means that your patch is more likely to be ignored by
+busy people. Please, just email the diffs.
+
+I wrote a little guide this week:
+
+
+
+The perfect patch. [email blocked]
+
+The latest version of this document may be found at
+http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt
+
+Delivery
+========
+
+- Patches are delivered via email only. Downloading them from internet
+ servers is a pain.
+
+- One patch per email, with the changelog in the body of the email.
+
+Subject:
+========
+
+- The email's Subject: should consisely describe the patch which that email
+ contains. The Subject: should not be a filename. Do not use the same
+ Subject: for every patch in a whole patch series.
+
+ Bear in mind that the Subject: of your email becomes a globally-unique
+ identifier for that patch. It propagates all the way into BitKeeper. The
+ Subject: may later be used in developer discussions which refer to the
+ patch. People will want to google for the patch's Subject: to read
+ discussion regarding that patch.
+
+- When sending a series of patches, the patches should be sequence-numbered
+ in the Subject:
+
+- It is nice if the Subject: includes mention of the subsystem which it
+ affects. See example below.
+
+- Example Subject:
+
+ [patch 2/5] ext2: improve scalability of bitmap searching
+
+- Note that various people's patch receiving scripts will strip away
+ Subject: text which is inside brackets []. So you should place information
+ which has no long-term relevance to the patch inside brackets. This
+ includes the word "patch" and any sequence numbering. The subsystem
+ identifier ("ext2:") should hence be outside brackets.
+
+
+Changelog
+=========
+
+- Bear in mind that the Subject: and changelog which you provide will
+ propagate all the way into the permanent kernel record. Other developers
+ will want to read and understand your patch and changelog years in the
+ future.
+
+ So the changelog should describe the patch fully:
+
+ - why the kernel needed patching
+
+ - the overall design approach in the patch
+
+ - implementation details
+
+ - testing results
+
+- Don't bother mentioning what version of the kernel the patch applies to
+ ("applies to 2.6.8-rc1"). This is not interesting information - once the
+ patch is in bitkeeper, of _course_ it applied, and it'll probably be merged
+ into a later kernel than the one which you wrote it for.
+
+- Do not refer to earlier patches when changelogging a new version of a
+ patch. It's not very useful to have a bitkeeper changelog which says "OK,
+ this fixes the things you mentioned yesterday". Each iteration of the patch
+ should contain a standalone changelog. This implies that you need a patch
+ management system which maintains changelogs. See below.
+
+- Add a Signed-off-by: line.
+
+- Most people's patch receiving scripts will treat a ^--- string as the
+ separator between the changelog and the patch itself. You can use this to
+ ensure that any diffstat information is discarded when the patch is applied:
+
+
+
+ Another few #if/#ifdef cleanups, this time for the PPC architecture.
+
+ Signed-off-by: <valdis.kletnieks@...edu>
+ Signed-off-by: Andrew Morton [email blocked]
+ ---
+
+ 25-akpm/arch/ppc/kernel/process.c | 2 +-
+ 25-akpm/arch/ppc/platforms/85xx/mpc85xx_cds_common.c | 2 +-
+ 25-akpm/arch/ppc/syslib/ppc85xx_setup.c | 4 ++--
+ 3 files changed, 4 insertions(+), 4 deletions(-)
+
+ --- 25/arch/ppc/kernel/process.c
+ +++ 25/arch/ppc/kernel/process.c
+ @@ -667,7 +667,7 @@ void show_stack(struct task_struct *tsk,
+
+
+The diff
+========
+
+- Patches should be in `patch -p1' form:
+
+ --- a/kernel/sched.c
+ +++ b/kernel/sched.c
+
+- Make sure that your patches apply to the latest version of the kernel
+ tree. Either straight from bitkeeper or from
+ ftp://ftp.kernel.org/pub/linux/kernel/v2.6/snapshots/
+
+- When raising patches for -mm it's generally best to base them on the
+ latest Linus tree. I'll work out any rejects/incompatibilities. There are
+ of course exceptions to this.
+
+- Ensure that your patch does not add new trailing whitespace. The below
+ script will fix up your patch by stripping off such whitespace.
+
+ #!/bin/sh
+
+ strip1()
+ {
+ TMP=$(mktemp /tmp/XXXXXX)
+ cp $1 $TMP
+ sed -e '/^+/s/[ ]*$//' < $TMP > $1
+ rm $TMP
+ }
+
+ for i in $*
+ do
+ strip1 $i
+ done
+
+
+Overall
+=======
+
+- Avoid MIME and attachements if possible. Make sure that your email client
+ does not wordwrap your patch. Make sure that your email client does not
+ replace tabs with spaces.
+
+ Mail yourself a decent-sized patch and check that it still applies.
+
+
+
+The patch management scripts at http://www.zip.com.au/~akpm/linux/patches/
+implement all of the above.
+
+The patch management tools at https://savannah.nongnu.org/projects/quilt/ also
+implement all of the above.
\ No newline at end of file
--
1.8.1.2
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
Powered by blists - more mailing lists