| 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: <1419352327-4517-6-git-send-email-corbet@lwn.net> Date: Tue, 23 Dec 2014 09:32:05 -0700 From: Jonathan Corbet <corbet@....net> To: linux-kernel@...r.kernel.org Cc: Randy Dunlap <rdunlap@...radead.org>, Jonathan Corbet <corbet@....net> Subject: [PATCH 5/7] Docs: SubmittingPatches: miscellaneous cleanups Changes to make the formatting a bit more consistent and fix up wording in various places. Signed-off-by: Jonathan Corbet <corbet@....net> --- Documentation/SubmittingPatches | 61 +++++++++++++++++++++++++---------------- 1 file changed, 38 insertions(+), 23 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index a8308401a048..e6cbe59d890f 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -10,14 +10,18 @@ kernel, the process can sometimes be daunting if you're not familiar with "the system." This text is a collection of suggestions which can greatly increase the chances of your change being accepted. -Read Documentation/SubmitChecklist for a list of items to check -before submitting code. If you are submitting a driver, also read +This document contains a large number of suggestions in a relatively terse +format. For detailed information on how the kernel development process +works, see Documentation/development-process. Also, read +Documentation/SubmitChecklist for a list of items to check before +submitting code. If you are submitting a driver, also read Documentation/SubmittingDrivers. Many of these steps describe the default behavior of the git version control system; if you use git to prepare your patches, you'll find much of the mechanical work done for you, though you'll still need to prepare -and document a sensible set of patches. +and document a sensible set of patches. In general, use of git will make +your life as a kernel developer easier. -------------------------------------------- SECTION 1 - CREATING AND SENDING YOUR CHANGE @@ -59,7 +63,7 @@ not in any lower subdirectory. To create a patch for a single file, it is often sufficient to do: - SRCTREE= linux-2.6 + SRCTREE= linux MYFILE= drivers/net/mydriver.c cd $SRCTREE @@ -72,17 +76,16 @@ To create a patch for multiple files, you should unpack a "vanilla", or unmodified kernel source tree, and generate a diff against your own source tree. For example: - MYSRC= /devel/linux-2.6 + MYSRC= /devel/linux - tar xvfz linux-2.6.12.tar.gz - mv linux-2.6.12 linux-2.6.12-vanilla - diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \ - linux-2.6.12-vanilla $MYSRC > /tmp/patch + tar xvfz linux-3.19.tar.gz + mv linux-3.19 linux-3.19-vanilla + diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \ + linux-3.19-vanilla $MYSRC > /tmp/patch "dontdiff" is a list of files which are generated by the kernel during the build process, and should be ignored in any diff(1)-generated -patch. The "dontdiff" file is included in the kernel tree in -2.6.12 and later. +patch. Make sure your patch does not include any extra files which do not belong in a patch submission. Make sure to review your patch -after- @@ -100,6 +103,7 @@ is another popular alternative. 2) Describe your changes. +------------------------- Describe your problem. Whether your patch is a one-line bug fix or 5000 lines of a new feature, there must be an underlying problem that @@ -141,10 +145,10 @@ See #3, next. When you submit or resubmit a patch or patch series, include the complete patch description and justification for it. Don't just say that this is version N of the patch (series). Don't expect the -patch merger to refer back to earlier patch versions or referenced +subsystem maintainer to refer back to earlier patch versions or referenced URLs to find the patch description and put that into the patch. I.e., the patch (series) and its description should be self-contained. -This benefits both the patch merger(s) and reviewers. Some reviewers +This benefits both the maintainers and reviewers. Some reviewers probably didn't even receive earlier versions of the patch. Describe your changes in imperative mood, e.g. "make xyzzy do frotz" @@ -194,8 +198,9 @@ outputting the above style in the git log or git show commands fixes = Fixes: %h (\"%s\") 3) Separate your changes. +------------------------- -Separate _logical changes_ into a single patch file. +Separate each _logical change_ into a separate patch. For example, if your changes include both bug fixes and performance enhancements for a single driver, separate those changes into two @@ -206,6 +211,10 @@ On the other hand, if you make a single change to numerous files, group those changes into a single patch. Thus a single logical change is contained within a single patch. +The point to remember is that each patch should make an easily understood +change that can be verified by reviewers. Each patch should be justifiable +on its own merits. + If one patch depends on another patch in order for a change to be complete, that is OK. Simply note "this patch depends on patch X" in your patch description. @@ -321,6 +330,7 @@ Trivial patches must qualify for one of the following rules: 6) No MIME, no links, no compression, no attachments. Just plain text. +----------------------------------------------------------------------- Linus and other kernel developers need to be able to read and comment on the changes you are submitting. It is important for a kernel @@ -344,15 +354,14 @@ See Documentation/email-clients.txt for hints about configuring your e-mail client so that it sends your patches untouched. 7) E-mail size. - -When sending patches to Linus, always follow step #7. +--------------- Large changes are not appropriate for mailing lists, and some maintainers. If your patch, uncompressed, exceeds 300 kB in size, it is preferred that you store your patch on an Internet-accessible -server, and provide instead a URL (link) pointing to your patch. - - +server, and provide instead a URL (link) pointing to your patch. But note +that if your patch exceeds 300 kB, it almost certainly needs to be broken up +anyway. 8) Respond to review comments. ------------------------------ @@ -385,6 +394,7 @@ busy times like merge windows. 10) Include PATCH in the subject +-------------------------------- Due to high e-mail traffic to Linus, and to linux-kernel, it is common convention to prefix your subject line with [PATCH]. This lets Linus @@ -394,6 +404,7 @@ e-mail discussions. 11) Sign your work +------------------ To improve tracking of who did what, especially with patches that can percolate to their final resting place in the kernel through several @@ -489,13 +500,14 @@ tree. 12) When to use Acked-by: and Cc: +--------------------------------- The Signed-off-by: tag indicates that the signer was involved in the development of the patch, or that he/she was in the patch's delivery path. If a person was not directly involved in the preparation or handling of a patch but wishes to signify and record their approval of it then they can -arrange to have an Acked-by: line added to the patch's changelog. +ask to have an Acked-by: line added to the patch's changelog. Acked-by: is often used by the maintainer of the affected code when that maintainer neither contributed to nor forwarded the patch. @@ -503,7 +515,8 @@ maintainer neither contributed to nor forwarded the patch. Acked-by: is not as formal as Signed-off-by:. It is a record that the acker has at least reviewed the patch and has indicated acceptance. Hence patch mergers will sometimes manually convert an acker's "yep, looks good to me" -into an Acked-by:. +into an Acked-by: (but note that it is usually better to ask for an +explicit ack). Acked-by: does not necessarily indicate acknowledgement of the entire patch. For example, if a patch affects multiple subsystems and has an Acked-by: from @@ -515,11 +528,13 @@ list archives. If a person has had the opportunity to comment on a patch, but has not provided such comments, you may optionally add a "Cc:" tag to the patch. This is the only tag which might be added without an explicit action by the -person it names. This tag documents that potentially interested parties -have been included in the discussion +person it names - but it should indicate that this person was copied on the +patch. This tag documents that potentially interested parties +have been included in the discussion. 13) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes: +-------------------------------------------------------------------------- The Reported-by tag gives credit to people who find bugs and report them and it hopefully inspires them to help us again in the future. Please note that if -- 2.1.0 -- 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