From 2b5588a1a80cdca86a85b0f32c072a7572dcf62b Mon Sep 17 00:00:00 2001 From: Kefu Chai Date: Wed, 20 Jan 2016 13:40:01 +0800 Subject: [PATCH] SubmittingPatches: update with reST syntax Signed-off-by: Kefu Chai --- SubmittingPatches.rst | 580 +++++++++++++++++++++--------------------- 1 file changed, 294 insertions(+), 286 deletions(-) diff --git a/SubmittingPatches.rst b/SubmittingPatches.rst index 05b62acbbc7ae..aa0013c4e9249 100644 --- a/SubmittingPatches.rst +++ b/SubmittingPatches.rst @@ -18,179 +18,178 @@ patches submitted to the project. These definitions are taken from those used by the Linux kernel and many other open source projects. -1) 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 -layers of maintainers, we've introduced a "sign-off" procedure on -patches that are being emailed around. - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as a open-source patch. The rules are pretty simple: if you -can certify the below: - - Developer's Certificate of Origin 1.1 - - By making a contribution to this project, I certify that: - - (a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - - (b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - - (c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - - (d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. - -then you just add a line saying - - Signed-off-by: Random J Developer - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -Some people also put extra tags at the end. They'll just be ignored for -now, but you can do this to mark internal company procedures or just -point out some special detail about the sign-off. - -If you are a subsystem or branch maintainer, sometimes you need to slightly -modify patches you receive in order to merge them, because the code is not -exactly the same in your tree and the submitters'. If you stick strictly to -rule (c), you should ask the submitter to rediff, but this is a totally -counter-productive waste of time and energy. Rule (b) allows you to adjust -the code, but then it is very impolite to change one submitter's code and -make them endorse your bugs. To solve this problem, it is recommended that -you add a line between the last Signed-off-by header and yours, indicating -the nature of your changes. While there is nothing mandatory about this, it -seems like prepending the description with your mail and/or name, all -enclosed in square brackets, is noticeable enough to make it obvious that -you are responsible for last-minute changes. Example : - - Signed-off-by: Random J Developer - [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] - Signed-off-by: Lucky K Maintainer - -This practise is particularly helpful if you maintain a stable branch and -want at the same time to credit the author, track changes, merge the fix, -and protect the submitter from complaints. Note that under no circumstances -can you change the author's identity (the From header), as it is the one -which appears in the changelog. - -Special note to back-porters: It seems to be a common and useful practise -to insert an indication of the origin of a patch at the top of the commit -message (just after the subject line) to facilitate tracking. For instance, -here's what we see in 2.6-stable : - - Date: Tue May 13 19:10:30 2008 +0000 +1. 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 + layers of maintainers, we've introduced a "sign-off" procedure on + patches that are being emailed around. + + The sign-off is a simple line at the end of the explanation for the + patch, which certifies that you wrote it or otherwise have the right to + pass it on as a open-source patch. The rules are pretty simple: if you + can certify the below: + + Developer's Certificate of Origin 1.1 + + By making a contribution to this project, I certify that: + + (a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + + (b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + + (c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + + (d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. + + then you just add a line saying :: + + Signed-off-by: Random J Developer + + + using your real name (sorry, no pseudonyms or anonymous contributions.) + + Some people also put extra tags at the end. They'll just be ignored for + now, but you can do this to mark internal company procedures or just + point out some special detail about the sign-off. + + If you are a subsystem or branch maintainer, sometimes you need to slightly + modify patches you receive in order to merge them, because the code is not + exactly the same in your tree and the submitters'. If you stick strictly to + rule (c), you should ask the submitter to rediff, but this is a totally + counter-productive waste of time and energy. Rule (b) allows you to adjust + the code, but then it is very impolite to change one submitter's code and + make them endorse your bugs. To solve this problem, it is recommended that + you add a line between the last Signed-off-by header and yours, indicating + the nature of your changes. While there is nothing mandatory about this, it + seems like prepending the description with your mail and/or name, all + enclosed in square brackets, is noticeable enough to make it obvious that + you are responsible for last-minute changes. Example :: + + Signed-off-by: Random J Developer + [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] + Signed-off-by: Lucky K Maintainer + + This practise is particularly helpful if you maintain a stable branch and + want at the same time to credit the author, track changes, merge the fix, + and protect the submitter from complaints. Note that under no circumstances + can you change the author's identity (the From header), as it is the one + which appears in the changelog. + + Special note to back-porters: It seems to be a common and useful practise + to insert an indication of the origin of a patch at the top of the commit + message (just after the subject line) to facilitate tracking. For instance, + here's what we see in 2.6-stable :: + + Date: Tue May 13 19:10:30 2008 +0000 SCSI: libiscsi regression in 2.6.25: fix nop timer handling commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream -And here's what appears in 2.4 : + And here's what appears in 2.4 :: - Date: Tue May 13 22:12:27 2008 +0200 + Date: Tue May 13 22:12:27 2008 +0200 wireless, airo: waitbusy() won't delay [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] -Whatever the format, this information provides a valuable help to people -tracking your trees, and to people trying to trouble-shoot bugs in your -tree. + Whatever the format, this information provides a valuable help to people + tracking your trees, and to people trying to trouble-shoot bugs in your + tree. +2. When to use ``Acked-by:`` and ``Cc:`` -2) 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. -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. -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. + ``Acked-by:`` is often used by the maintainer of the affected code when that + maintainer neither contributed to nor forwarded the patch. -Acked-by: is often used by the maintainer of the affected code when that -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:``. -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:. + ``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 + one subsystem maintainer then this usually indicates acknowledgement of just + the part which affects that maintainer's code. Judgement should be used here. + When in doubt people should refer to the original discussion in the mailing + list archives. -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 -one subsystem maintainer then this usually indicates acknowledgement of just -the part which affects that maintainer's code. Judgement should be used here. -When in doubt people should refer to the original discussion in the mailing -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 -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 +3. Using ``Reported-by:``, ``Tested-by:`` and ``Reviewed-by:`` + If this patch fixes a problem reported by somebody else, consider adding a + Reported-by: tag to credit the reporter for their contribution. Please + note that this tag should not be added without the reporter's permission, + especially if the problem was not reported in a public forum. That said, + if we diligently credit our bug reporters, they will, hopefully, be + inspired to help us again in the future. -3) Using Reported-by:, Tested-by: and Reviewed-by: + A ``Tested-by:`` tag indicates that the patch has been successfully tested (in + some environment) by the person named. This tag informs maintainers that + some testing has been performed, provides a means to locate testers for + future patches, and ensures credit for the testers. -If this patch fixes a problem reported by somebody else, consider adding a -Reported-by: tag to credit the reporter for their contribution. Please -note that this tag should not be added without the reporter's permission, -especially if the problem was not reported in a public forum. That said, -if we diligently credit our bug reporters, they will, hopefully, be -inspired to help us again in the future. + ``Reviewed-by:``, instead, indicates that the patch has been reviewed and found + acceptable according to the Reviewer's Statement: -A Tested-by: tag indicates that the patch has been successfully tested (in -some environment) by the person named. This tag informs maintainers that -some testing has been performed, provides a means to locate testers for -future patches, and ensures credit for the testers. + Reviewer's statement of oversight -Reviewed-by:, instead, indicates that the patch has been reviewed and found -acceptable according to the Reviewer's Statement: + By offering my ``Reviewed-by:`` tag, I state that: - Reviewer's statement of oversight + (a) I have carried out a technical review of this patch to + evaluate its appropriateness and readiness for inclusion into + the mainline kernel. - By offering my Reviewed-by: tag, I state that: + (b) Any problems, concerns, or questions relating to the patch + have been communicated back to the submitter. I am satisfied + with the submitter's response to my comments. - (a) I have carried out a technical review of this patch to - evaluate its appropriateness and readiness for inclusion into - the mainline kernel. + (c) While there may be things that could be improved with this + submission, I believe that it is, at this time, (1) a + worthwhile modification to the kernel, and (2) free of known + issues which would argue against its inclusion. - (b) Any problems, concerns, or questions relating to the patch - have been communicated back to the submitter. I am satisfied - with the submitter's response to my comments. + (d) While I have reviewed the patch and believe it to be sound, I + do not (unless explicitly stated elsewhere) make any + warranties or guarantees that it will achieve its stated + purpose or function properly in any given situation. - (c) While there may be things that could be improved with this - submission, I believe that it is, at this time, (1) a - worthwhile modification to the kernel, and (2) free of known - issues which would argue against its inclusion. - - (d) While I have reviewed the patch and believe it to be sound, I - do not (unless explicitly stated elsewhere) make any - warranties or guarantees that it will achieve its stated - purpose or function properly in any given situation. - -A Reviewed-by tag is a statement of opinion that the patch is an -appropriate modification of the kernel without any remaining serious -technical issues. Any interested reviewer (who has done the work) can -offer a Reviewed-by tag for a patch. This tag serves to give credit to -reviewers and to inform maintainers of the degree of review which has been -done on the patch. Reviewed-by: tags, when supplied by reviewers known to -understand the subject area and to perform thorough reviews, will normally -increase the likelihood of your patch getting into the kernel. + A ``Reviewed-by`` tag is a statement of opinion that the patch is an + appropriate modification of the kernel without any remaining serious + technical issues. Any interested reviewer (who has done the work) can + offer a ``Reviewed-by`` tag for a patch. This tag serves to give credit to + reviewers and to inform maintainers of the degree of review which has been + done on the patch. ``Reviewed-by:`` tags, when supplied by reviewers known to + understand the subject area and to perform thorough reviews, will normally + increase the likelihood of your patch getting into the kernel. ----------------------------- @@ -207,212 +206,221 @@ a published git tree (usually on github), or via patches emailed directly to the email list (ceph-devel@vger.kernel.org). Github is preferred due to the convenience of the 'pull request' feature. -1) Github pull request +1. Github pull request + + The preferred way to submit code is by publishing your patches in a branch + in your github fork of the ceph repository and then submitting a github + pull request. -The preferred way to submit code is by publishing your patches in a branch -in your github fork of the ceph repository and then submitting a github -pull request. + For example, prepare your changes -For example, prepare your changes: + .. code-block:: bash - $ git checkout -b mything - ...code furiously... - $ git commit # git gui is also quite convenient - $ git push origin mything + # ...code furiously... + $ git commit # git gui is also quite convenient + $ git push origin mything -Then submit a pull request at + Then submit a pull request at https://github.com/ceph/ceph/pulls -and click 'New pull request'. The 'hub' command-line tool, available from + and click 'New pull request'. The 'hub' command-line tool, available from - https://github.com/github/hub + https://github.com/github/hub -allows you to submit pull requests directly from the command line: + allows you to submit pull requests directly from the command line - $ hub pull-request -b ceph:master -h you:mything + .. code-block:: bash -Pull requests appear in the review queue at + $ hub pull-request -b ceph:master -h you:mything + + Pull requests appear in the review queue at https://github.com/organizations/ceph/dashboard/pulls -You may want to ping a developer in #ceph-devel on irc.oftc.net or on the -email list to ensure your submission is noticed. + You may want to ping a developer in #ceph-devel on irc.oftc.net or on the + email list to ensure your submission is noticed. + + When addressing review comments, can should either add additional patches to + your branch or (better yet) squash those changes into the relevant commits so + that the sequence of changes is "clean" and gets things right the first time. + The 'git rebase -i' command is very helpful in this process. Once you have + updated your local branch, you can simply force-push to the existing branch + in your public repository that is referenced by the pull request with -When addressing review comments, can should either add additional patches to -your branch or (better yet) squash those changes into the relevant commits so -that the sequence of changes is "clean" and gets things right the first time. -The 'git rebase -i' command is very helpful in this process. Once you have -updated your local branch, you can simply force-push to the existing branch -in your public repository that is referenced by the pull request with + .. code-block:: bash - $ git push -f origin mything + $ git push -f origin mything -and your changes will be visible from the existing pull-request. You may want -to ping the reviewer again or comment on the pull request to ensure the updates -are noticed. + and your changes will be visible from the existing pull-request. You may want + to ping the reviewer again or comment on the pull request to ensure the updates + are noticed. -Q: Which branch should I target in my pull request? + Q: Which branch should I target in my pull request? -A: The target branch depends on the nature of your change: + A: The target branch depends on the nature of your change: - If you are adding a feature, target the "master" branch in your pull - request. + If you are adding a feature, target the "master" branch in your pull + request. - If you are fixing a bug, target the named branch corresponding to the - major version that is currently in development. For example, if - Infernalis is the latest stable release and Jewel is development, target - the "jewel" branch for bugfixes. The Ceph core developers will - periodically merge this named branch into "master". When this happens, - the master branch will contain your fix as well. + If you are fixing a bug, target the named branch corresponding to the + major version that is currently in development. For example, if + Infernalis is the latest stable release and Jewel is development, target + the "jewel" branch for bugfixes. The Ceph core developers will + periodically merge this named branch into "master". When this happens, + the master branch will contain your fix as well. - If you are fixing a bug (see above) *and* the bug exists in older stable - branches (for example, the "hammer" or "infernalis" branches), then you - should file a Redmine ticket describing your issue and fill out the - "Backport: " form field. This will notify other developers that - your commit should be cherry-picked to these stable branches. For example, - you should set "Backport: hammer" in your Redmine ticket to indicate that - you are fixing a bug that exists on the "hammer" branch and that you - desire that your change be cherry-picked to that branch. + If you are fixing a bug (see above) *and* the bug exists in older stable + branches (for example, the "hammer" or "infernalis" branches), then you + should file a Redmine ticket describing your issue and fill out the + "Backport: " form field. This will notify other developers that + your commit should be cherry-picked to these stable branches. For example, + you should set "Backport: hammer" in your Redmine ticket to indicate that + you are fixing a bug that exists on the "hammer" branch and that you + desire that your change be cherry-picked to that branch. -Q: How to include Reviewed-by: tag(s) in my pull request? + Q: How to include ``Reviewed-by: tag(s)`` in my pull request? - You don't. If someone reviews your pull request, they should indicate they - have done so by commenting on it with "+1", "looks good to me", "LGTM", - and/or the entire "Reviewed-by: ..." line with their name and email address. + You don't. If someone reviews your pull request, they should indicate they + have done so by commenting on it with "+1", "looks good to me", "LGTM", + and/or the entire "Reviewed-by: ..." line with their name and email address. - The developer merging the pull request should note positive reviews and - include the appropriate Reviewed-by: lines in the merge commit. + The developer merging the pull request should note positive reviews and + include the appropriate Reviewed-by: lines in the merge commit. -2) Patch submission via ceph-devel@vger.kernel.org +2. Patch submission via ceph-devel@vger.kernel.org -The best way to generate a patch for manual submission is to work from -a Git checkout of the Ceph source code. You can then generate patches -with the 'git format-patch' command. For example, + The best way to generate a patch for manual submission is to work from + a Git checkout of the Ceph source code. You can then generate patches + with the 'git format-patch' command. For example, - $ git format-patch HEAD^^ -o mything + .. code-block:: bash -will take the last two commits and generate patches in the mything/ -directory. The commit you specify on the command line is the -'upstream' commit that you are diffing against. Note that it does -not necesarily have to be an ancestor of your current commit. You -can do something like + $ git format-patch HEAD^^ -o mything - $ git checkout -b mything - $ ... do lots of stuff ... - $ git fetch - ...find out that origin/unstable has also moved forward... - $ git format-patch origin/unstable -o mything + will take the last two commits and generate patches in the mything/ + directory. The commit you specify on the command line is the + 'upstream' commit that you are diffing against. Note that it does + not necesarily have to be an ancestor of your current commit. You + can do something like -and the patches will be against origin/unstable. + .. code-block:: bash -The -o dir is optional; if left off, the patch(es) will appear in -the current directory. This can quickly get messy. + $ git checkout -b mything + # ... do lots of stuff ... + $ git fetch + # ...find out that origin/unstable has also moved forward... + $ git format-patch origin/unstable -o mything -You can also add --cover-letter and get a '0000' patch in the -mything/ directory. That can be updated to include any overview -stuff for a multipart patch series. If it's a single patch, don't -bother. + and the patches will be against origin/unstable. -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- -generated it with diff(1), to ensure accuracy. + The ``-o`` dir is optional; if left off, the patch(es) will appear in + the current directory. This can quickly get messy. -If your changes produce a lot of deltas, you may want to look into -splitting them into individual patches which modify things in -logical stages. This will facilitate easier reviewing by other -kernel developers, very important if you want your patch accepted. -There are a number of scripts which can aid in this. + You can also add ``--cover-letter`` and get a '0000' patch in the + mything/ directory. That can be updated to include any overview + stuff for a multipart patch series. If it's a single patch, don't + bother. -The git send-email command make it super easy to send patches -(particularly those prepared with git format patch). It is careful to -format the emails correctly so that you don't have to worry about your -email client mangling whitespace or otherwise screwing things up. It -works like so: + 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- + generated it with ``diff(1)``, to ensure accuracy. - $ git send-email --to ceph-devel@vger.kernel.org my.patch + If your changes produce a lot of deltas, you may want to look into + splitting them into individual patches which modify things in + logical stages. This will facilitate easier reviewing by other + kernel developers, very important if you want your patch accepted. + There are a number of scripts which can aid in this. -for a single patch, or + The ``git send-email`` command make it super easy to send patches + (particularly those prepared with git format patch). It is careful to + format the emails correctly so that you don't have to worry about your + email client mangling whitespace or otherwise screwing things up. It + works like so: - $ git send-email --to ceph-devel@vger.kernel.org mything + .. code-block:: bash -to send a whole patch series (prepared with, say, git format-patch). + $ git send-email --to ceph-devel@vger.kernel.org my.patch + for a single patch, or -3) Describe your changes. + .. code-block:: bash -Describe the technical detail of the change(s) your patch includes. + $ git send-email --to ceph-devel@vger.kernel.org mything -Be as specific as possible. The WORST descriptions possible include -things like "update driver X", "bug fix for driver X", or "this patch -includes updates for subsystem X. Please apply." + to send a whole patch series (prepared with, say, git format-patch). -The maintainer will thank you if you write your patch description in a -form which can be easily pulled into Linux's source code management -system, git, as a "commit log". See #15, below. -If your description starts to get long, that's a sign that you probably -need to split up your patch. See #3, next. +3. Describe your changes. -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 -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 -probably didn't even receive earlier versions of the patch. + Describe the technical detail of the change(s) your patch includes. -If the patch fixes a logged bug entry, refer to that bug entry by -number and URL. + Be as specific as possible. The WORST descriptions possible include + things like "update driver X", "bug fix for driver X", or "this patch + includes updates for subsystem X. Please apply." + The maintainer will thank you if you write your patch description in a + form which can be easily pulled into Linux's source code management + system, git, as a "commit log". See #15, below. -4) Separate your changes. + If your description starts to get long, that's a sign that you probably + need to split up your patch. See #3, next. -Separate _logical changes_ into a single patch file. + 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 + 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 + probably didn't even receive earlier versions of the patch. -For example, if your changes include both bug fixes and performance -enhancements for a single driver, separate those changes into two -or more patches. If your changes include an API update, and a new -driver which uses that new API, separate those into two patches. + If the patch fixes a logged bug entry, refer to that bug entry by + number and URL. -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. -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. +4. Separate your changes. -If you cannot condense your patch set into a smaller set of patches, -then only post say 15 or so at a time and wait for review and integration. + Separate *logical changes* into a single patch file. + For example, if your changes include both bug fixes and performance + enhancements for a single driver, separate those changes into two + or more patches. If your changes include an API update, and a new + driver which uses that new API, separate those into two patches. + 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. -5) Style check your changes. + 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. -Check your patch for basic style violations, details of which can be -found in CodingStyle. + If you cannot condense your patch set into a smaller set of patches, + then only post say 15 or so at a time and wait for review and integration. +5. Style check your changes. + Check your patch for basic style violations, details of which can be + found in CodingStyle. -6) No MIME, no links, no compression, no attachments. Just plain text. +6. No MIME, no links, no compression, no attachments. Just plain text. -Developers need to be able to read and comment on the changes you are -submitting. It is important for a kernel developer to be able to -"quote" your changes, using standard e-mail tools, so that they may -comment on specific portions of your code. + Developers need to be able to read and comment on the changes you are + submitting. It is important for a kernel developer to be able to + "quote" your changes, using standard e-mail tools, so that they may + comment on specific portions of your code. -For this reason, all patches should be submitting e-mail "inline". -WARNING: Be wary of your editor's word-wrap corrupting your patch, -if you choose to cut-n-paste your patch. + For this reason, all patches should be submitting e-mail "inline". + WARNING: Be wary of your editor's word-wrap corrupting your patch, + if you choose to cut-n-paste your patch. -Do not attach the patch as a MIME attachment, compressed or not. -Many popular e-mail applications will not always transmit a MIME -attachment as plain text, making it impossible to comment on your -code. A MIME attachment also takes Linus a bit more time to process, -decreasing the likelihood of your MIME-attached change being accepted. + Do not attach the patch as a MIME attachment, compressed or not. + Many popular e-mail applications will not always transmit a MIME + attachment as plain text, making it impossible to comment on your + code. A MIME attachment also takes Linus a bit more time to process, + decreasing the likelihood of your MIME-attached change being accepted. -Exception: If your mailer is mangling patches then someone may ask -you to re-send them using MIME. + Exception: If your mailer is mangling patches then someone may ask + you to re-send them using MIME. -- 2.39.5