summaryrefslogtreecommitdiff
path: root/Documentation/SubmittingPatches
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab@s-opensource.com>2016-09-21 08:40:21 -0300
committerMauro Carvalho Chehab <mchehab@s-opensource.com>2016-10-24 08:12:35 -0200
commit186128f75392f8478ad1b32a675627d738881ca4 (patch)
treec72c5e91c636e58ae0a9496fb2759074f484244f /Documentation/SubmittingPatches
parent0e4f07a65f53e7b3afab71925e56fe6aaa07d696 (diff)
docs-rst: add documents to development-process
Add several documents to the development-process ReST book. As we don't want renames, use symlinks instead, keeping those documents on their original place. Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Diffstat (limited to 'Documentation/SubmittingPatches')
-rw-r--r--Documentation/SubmittingPatches841
1 files changed, 0 insertions, 841 deletions
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
deleted file mode 100644
index e62ddcdcaf5d..000000000000
--- a/Documentation/SubmittingPatches
+++ /dev/null
@@ -1,841 +0,0 @@
-.. _submittingpatches:
-
-How to Get Your Change Into the Linux Kernel or Care And Operation Of Your Linus Torvalds
-=========================================================================================
-
-For a person or company who wishes to submit a change to the Linux
-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.
-
-This document contains a large number of suggestions in a relatively terse
-format. For detailed information on how the kernel development process
-works, see :ref:`Documentation/process <development_process_main>`.
-Also, read :ref:`Documentation/SubmitChecklist <submitchecklist>`
-for a list of items to check before
-submitting code. If you are submitting a driver, also read
-:ref:`Documentation/SubmittingDrivers <submittingdrivers>`;
-for device tree binding patches, read
-Documentation/devicetree/bindings/submitting-patches.txt.
-
-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. In general, use of ``git`` will make
-your life as a kernel developer easier.
-
-Creating and Sending your Change
-********************************
-
-
-0) Obtain a current source tree
--------------------------------
-
-If you do not have a repository with the current kernel source handy, use
-``git`` to obtain one. You'll want to start with the mainline repository,
-which can be grabbed with::
-
- git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-
-Note, however, that you may not want to develop against the mainline tree
-directly. Most subsystem maintainers run their own trees and want to see
-patches prepared against those trees. See the **T:** entry for the subsystem
-in the MAINTAINERS file to find that tree, or simply ask the maintainer if
-the tree is not listed there.
-
-It is still possible to download kernel releases via tarballs (as described
-in the next section), but that is the hard way to do kernel development.
-
-1) ``diff -up``
----------------
-
-If you must generate your patches by hand, use ``diff -up`` or ``diff -uprN``
-to create patches. Git generates patches in this form by default; if
-you're using ``git``, you can skip this section entirely.
-
-All changes to the Linux kernel occur in the form of patches, as
-generated by :manpage:`diff(1)`. When creating your patch, make sure to
-create it in "unified diff" format, as supplied by the ``-u`` argument
-to :manpage:`diff(1)`.
-Also, please use the ``-p`` argument which shows which C function each
-change is in - that makes the resultant ``diff`` a lot easier to read.
-Patches should be based in the root kernel source directory,
-not in any lower subdirectory.
-
-To create a patch for a single file, it is often sufficient to do::
-
- SRCTREE= linux
- MYFILE= drivers/net/mydriver.c
-
- cd $SRCTREE
- cp $MYFILE $MYFILE.orig
- vi $MYFILE # make your change
- cd ..
- diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch
-
-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
-
- 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 :manpage:`diff(1)`-generated
-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-
-generating it with :manpage:`diff(1)`, to ensure accuracy.
-
-If your changes produce a lot of deltas, you need to split them into
-individual patches which modify things in logical stages; see
-:ref:`split_changes`. This will facilitate review by other kernel developers,
-very important if you want your patch accepted.
-
-If you're using ``git``, ``git rebase -i`` can help you with this process. If
-you're not using ``git``, ``quilt`` <http://savannah.nongnu.org/projects/quilt>
-is another popular alternative.
-
-.. _describe_changes:
-
-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
-motivated you to do this work. Convince the reviewer that there is a
-problem worth fixing and that it makes sense for them to read past the
-first paragraph.
-
-Describe user-visible impact. Straight up crashes and lockups are
-pretty convincing, but not all bugs are that blatant. Even if the
-problem was spotted during code review, describe the impact you think
-it can have on users. Keep in mind that the majority of Linux
-installations run kernels from secondary stable trees or
-vendor/product-specific trees that cherry-pick only specific patches
-from upstream, so include anything that could help route your change
-downstream: provoking circumstances, excerpts from dmesg, crash
-descriptions, performance regressions, latency spikes, lockups, etc.
-
-Quantify optimizations and trade-offs. If you claim improvements in
-performance, memory consumption, stack footprint, or binary size,
-include numbers that back them up. But also describe non-obvious
-costs. Optimizations usually aren't free but trade-offs between CPU,
-memory, and readability; or, when it comes to heuristics, between
-different workloads. Describe the expected downsides of your
-optimization so that the reviewer can weigh costs against benefits.
-
-Once the problem is established, describe what you are actually doing
-about it in technical detail. It's important to describe the change
-in plain English for the reviewer to verify that the code is behaving
-as you intend it to.
-
-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 :ref:`explicit_in_reply_to`.
-
-Solve only one problem per patch. If your description starts to get
-long, that's a sign that you probably need to split up your patch.
-See :ref:`split_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
-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 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"
-instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy
-to do frotz", as if you are giving orders to the codebase to change
-its behaviour.
-
-If the patch fixes a logged bug entry, refer to that bug entry by
-number and URL. If the patch follows from a mailing list discussion,
-give a URL to the mailing list archive; use the https://lkml.kernel.org/
-redirector with a ``Message-Id``, to ensure that the links cannot become
-stale.
-
-However, try to make your explanation understandable without external
-resources. In addition to giving a URL to a mailing list archive or
-bug, summarize the relevant points of the discussion that led to the
-patch as submitted.
-
-If you want to refer to a specific commit, don't just refer to the
-SHA-1 ID of the commit. Please also include the oneline summary of
-the commit, to make it easier for reviewers to know what it is about.
-Example::
-
- Commit e21d2170f36602ae2708 ("video: remove unnecessary
- platform_set_drvdata()") removed the unnecessary
- platform_set_drvdata(), but left the variable "dev" unused,
- delete it.
-
-You should also be sure to use at least the first twelve characters of the
-SHA-1 ID. The kernel repository holds a *lot* of objects, making
-collisions with shorter IDs a real possibility. Bear in mind that, even if
-there is no collision with your six-character ID now, that condition may
-change five years from now.
-
-If your patch fixes a bug in a specific commit, e.g. you found an issue using
-``git bisect``, please use the 'Fixes:' tag with the first 12 characters of
-the SHA-1 ID, and the one line summary. For example::
-
- Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()")
-
-The following ``git config`` settings can be used to add a pretty format for
-outputting the above style in the ``git log`` or ``git show`` commands::
-
- [core]
- abbrev = 12
- [pretty]
- fixes = Fixes: %h (\"%s\")
-
-.. _split_changes:
-
-3) Separate your changes
-------------------------
-
-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
-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.
-
-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.
-
-When dividing your change into a series of patches, take special care to
-ensure that the kernel builds and runs properly after each patch in the
-series. Developers using ``git bisect`` to track down a problem can end up
-splitting your patch series at any point; they will not thank you if you
-introduce bugs in the middle.
-
-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.
-
-
-
-4) Style-check your changes
----------------------------
-
-Check your patch for basic style violations, details of which can be
-found in
-:ref:`Documentation/CodingStyle <codingstyle>`.
-Failure to do so simply wastes
-the reviewers time and will get your patch rejected, probably
-without even being read.
-
-One significant exception is when moving code from one file to
-another -- in this case you should not modify the moved code at all in
-the same patch which moves it. This clearly delineates the act of
-moving the code and your changes. This greatly aids review of the
-actual differences and allows tools to better track the history of
-the code itself.
-
-Check your patches with the patch style checker prior to submission
-(scripts/checkpatch.pl). Note, though, that the style checker should be
-viewed as a guide, not as a replacement for human judgment. If your code
-looks better with a violation then its probably best left alone.
-
-The checker reports at three levels:
- - ERROR: things that are very likely to be wrong
- - WARNING: things requiring careful review
- - CHECK: things requiring thought
-
-You should be able to justify all violations that remain in your
-patch.
-
-
-5) Select the recipients for your patch
----------------------------------------
-
-You should always copy the appropriate subsystem maintainer(s) on any patch
-to code that they maintain; look through the MAINTAINERS file and the
-source code revision history to see who those maintainers are. The
-script scripts/get_maintainer.pl can be very useful at this step. If you
-cannot find a maintainer for the subsystem you are working on, Andrew
-Morton (akpm@linux-foundation.org) serves as a maintainer of last resort.
-
-You should also normally choose at least one mailing list to receive a copy
-of your patch set. linux-kernel@vger.kernel.org functions as a list of
-last resort, but the volume on that list has caused a number of developers
-to tune it out. Look in the MAINTAINERS file for a subsystem-specific
-list; your patch will probably get more attention there. Please do not
-spam unrelated lists, though.
-
-Many kernel-related lists are hosted on vger.kernel.org; you can find a
-list of them at http://vger.kernel.org/vger-lists.html. There are
-kernel-related lists hosted elsewhere as well, though.
-
-Do not send more than 15 patches at once to the vger mailing lists!!!
-
-Linus Torvalds is the final arbiter of all changes accepted into the
-Linux kernel. His e-mail address is <torvalds@linux-foundation.org>.
-He gets a lot of e-mail, and, at this point, very few patches go through
-Linus directly, so typically you should do your best to -avoid-
-sending him e-mail.
-
-If you have a patch that fixes an exploitable security bug, send that patch
-to security@kernel.org. For severe bugs, a short embargo may be considered
-to allow distributors to get the patch out to users; in such cases,
-obviously, the patch should not be sent to any public lists.
-
-Patches that fix a severe bug in a released kernel should be directed
-toward the stable maintainers by putting a line like this::
-
- Cc: stable@vger.kernel.org
-
-into the sign-off area of your patch (note, NOT an email recipient). You
-should also read
-:ref:`Documentation/stable_kernel_rules.txt <stable_kernel_rules>`
-in addition to this file.
-
-Note, however, that some subsystem maintainers want to come to their own
-conclusions on which patches should go to the stable trees. The networking
-maintainer, in particular, would rather not see individual developers
-adding lines like the above to their patches.
-
-If changes affect userland-kernel interfaces, please send the MAN-PAGES
-maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at
-least a notification of the change, so that some information makes its way
-into the manual pages. User-space API changes should also be copied to
-linux-api@vger.kernel.org.
-
-For small patches you may want to CC the Trivial Patch Monkey
-trivial@kernel.org which collects "trivial" patches. Have a look
-into the MAINTAINERS file for its current manager.
-
-Trivial patches must qualify for one of the following rules:
-
-- Spelling fixes in documentation
-- Spelling fixes for errors which could break :manpage:`grep(1)`
-- Warning fixes (cluttering with useless warnings is bad)
-- Compilation fixes (only if they are actually correct)
-- Runtime fixes (only if they actually fix things)
-- Removing use of deprecated functions/macros
-- Contact detail and documentation fixes
-- Non-portable code replaced by portable code (even in arch-specific,
- since people copy, as long as it's trivial)
-- Any fix by the author/maintainer of the file (ie. patch monkey
- in re-transmission mode)
-
-
-
-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
-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 submitted by 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.
-
-Exception: If your mailer is mangling patches then someone may ask
-you to re-send them using MIME.
-
-See :ref:`Documentation/email-clients.txt <email_clients>`
-for hints about configuring your e-mail client so that it sends your patches
-untouched.
-
-7) E-mail size
---------------
-
-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. But note
-that if your patch exceeds 300 kB, it almost certainly needs to be broken up
-anyway.
-
-8) Respond to review comments
------------------------------
-
-Your patch will almost certainly get comments from reviewers on ways in
-which the patch can be improved. You must respond to those comments;
-ignoring reviewers is a good way to get ignored in return. Review comments
-or questions that do not lead to a code change should almost certainly
-bring about a comment or changelog entry so that the next reviewer better
-understands what is going on.
-
-Be sure to tell the reviewers what changes you are making and to thank them
-for their time. Code review is a tiring and time-consuming process, and
-reviewers sometimes get grumpy. Even in that case, though, respond
-politely and address the problems they have pointed out.
-
-
-9) Don't get discouraged - or impatient
----------------------------------------
-
-After you have submitted your change, be patient and wait. Reviewers are
-busy people and may not get to your patch right away.
-
-Once upon a time, patches used to disappear into the void without comment,
-but the development process works more smoothly than that now. You should
-receive comments within a week or so; if that does not happen, make sure
-that you have sent your patches to the right place. Wait for a minimum of
-one week before resubmitting or pinging reviewers - possibly longer during
-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
-and other kernel developers more easily distinguish patches from other
-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
-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 an 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 <random@developer.example.org>
-
-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 him 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 <random@developer.example.org>
- [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h]
- Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org>
-
-This practice 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 practice
-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 a 3.x-stable release::
-
- Date: Tue Oct 7 07:26:38 2014 -0400
-
- libata: Un-break ATA blacklist
-
- commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream.
-
-And here's what might appear in an older kernel once a patch is backported::
-
- 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 troubleshoot bugs in your
-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
-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.
-
-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: (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
-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 - 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
-the bug was reported in private, then ask for permission first before using the
-Reported-by tag.
-
-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.
-
-Reviewed-by:, instead, indicates that the patch has been reviewed and found
-acceptable according to the Reviewer's Statement:
-
-Reviewer's statement of oversight
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-By offering my Reviewed-by: tag, I state that:
-
- (a) I have carried out a technical review of this patch to
- evaluate its appropriateness and readiness for inclusion into
- the mainline kernel.
-
- (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.
-
- (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 Suggested-by: tag indicates that the patch idea is suggested by the person
-named and ensures credit to the person for the idea. Please note that this
-tag should not be added without the reporter's permission, especially if the
-idea was not posted in a public forum. That said, if we diligently credit our
-idea reporters, they will, hopefully, be inspired to help us again in the
-future.
-
-A Fixes: tag indicates that the patch fixes an issue in a previous commit. It
-is used to make it easy to determine where a bug originated, which can help
-review a bug fix. This tag also assists the stable kernel team in determining
-which stable kernel versions should receive your fix. This is the preferred
-method for indicating a bug fixed by the patch. See :ref:`describe_changes`
-for more details.
-
-
-14) The canonical patch format
-------------------------------
-
-This section describes how the patch itself should be formatted. Note
-that, if you have your patches stored in a ``git`` repository, proper patch
-formatting can be had with ``git format-patch``. The tools cannot create
-the necessary text, though, so read the instructions below anyway.
-
-The canonical patch subject line is::
-
- Subject: [PATCH 001/123] subsystem: summary phrase
-
-The canonical patch message body contains the following:
-
- - A ``from`` line specifying the patch author (only needed if the person
- sending the patch is not the author).
-
- - An empty line.
-
- - The body of the explanation, line wrapped at 75 columns, which will
- be copied to the permanent changelog to describe this patch.
-
- - The ``Signed-off-by:`` lines, described above, which will
- also go in the changelog.
-
- - A marker line containing simply ``---``.
-
- - Any additional comments not suitable for the changelog.
-
- - The actual patch (``diff`` output).
-
-The Subject line format makes it very easy to sort the emails
-alphabetically by subject line - pretty much any email reader will
-support that - since because the sequence number is zero-padded,
-the numerical and alphabetic sort is the same.
-
-The ``subsystem`` in the email's Subject should identify which
-area or subsystem of the kernel is being patched.
-
-The ``summary phrase`` in the email's Subject should concisely
-describe the patch which that email contains. The ``summary
-phrase`` should not be a filename. Do not use the same ``summary
-phrase`` for every patch in a whole patch series (where a ``patch
-series`` is an ordered sequence of multiple, related patches).
-
-Bear in mind that the ``summary phrase`` of your email becomes a
-globally-unique identifier for that patch. It propagates all the way
-into the ``git`` changelog. The ``summary phrase`` may later be used in
-developer discussions which refer to the patch. People will want to
-google for the ``summary phrase`` to read discussion regarding that
-patch. It will also be the only thing that people may quickly see
-when, two or three months later, they are going through perhaps
-thousands of patches using tools such as ``gitk`` or ``git log
---oneline``.
-
-For these reasons, the ``summary`` must be no more than 70-75
-characters, and it must describe both what the patch changes, as well
-as why the patch might be necessary. It is challenging to be both
-succinct and descriptive, but that is what a well-written summary
-should do.
-
-The ``summary phrase`` may be prefixed by tags enclosed in square
-brackets: "Subject: [PATCH <tag>...] <summary phrase>". The tags are
-not considered part of the summary phrase, but describe how the patch
-should be treated. Common tags might include a version descriptor if
-the multiple versions of the patch have been sent out in response to
-comments (i.e., "v1, v2, v3"), or "RFC" to indicate a request for
-comments. If there are four patches in a patch series the individual
-patches may be numbered like this: 1/4, 2/4, 3/4, 4/4. This assures
-that developers understand the order in which the patches should be
-applied and that they have reviewed or applied all of the patches in
-the patch series.
-
-A couple of example Subjects::
-
- Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching
- Subject: [PATCH v2 01/27] x86: fix eflags tracking
-
-The ``from`` line must be the very first line in the message body,
-and has the form:
-
- From: Original Author <author@example.com>
-
-The ``from`` line specifies who will be credited as the author of the
-patch in the permanent changelog. If the ``from`` line is missing,
-then the ``From:`` line from the email header will be used to determine
-the patch author in the changelog.
-
-The explanation body will be committed to the permanent source
-changelog, so should make sense to a competent reader who has long
-since forgotten the immediate details of the discussion that might
-have led to this patch. Including symptoms of the failure which the
-patch addresses (kernel log messages, oops messages, etc.) is
-especially useful for people who might be searching the commit logs
-looking for the applicable patch. If a patch fixes a compile failure,
-it may not be necessary to include _all_ of the compile failures; just
-enough that it is likely that someone searching for the patch can find
-it. As in the ``summary phrase``, it is important to be both succinct as
-well as descriptive.
-
-The ``---`` marker line serves the essential purpose of marking for patch
-handling tools where the changelog message ends.
-
-One good use for the additional comments after the ``---`` marker is for
-a ``diffstat``, to show what files have changed, and the number of
-inserted and deleted lines per file. A ``diffstat`` is especially useful
-on bigger patches. Other comments relevant only to the moment or the
-maintainer, not suitable for the permanent changelog, should also go
-here. A good example of such comments might be ``patch changelogs``
-which describe what has changed between the v1 and v2 version of the
-patch.
-
-If you are going to include a ``diffstat`` after the ``---`` marker, please
-use ``diffstat`` options ``-p 1 -w 70`` so that filenames are listed from
-the top of the kernel source tree and don't use too much horizontal
-space (easily fit in 80 columns, maybe with some indentation). (``git``
-generates appropriate diffstats by default.)
-
-See more details on the proper patch format in the following
-references.
-
-.. _explicit_in_reply_to:
-
-15) Explicit In-Reply-To headers
---------------------------------
-
-It can be helpful to manually add In-Reply-To: headers to a patch
-(e.g., when using ``git send-email``) to associate the patch with
-previous relevant discussion, e.g. to link a bug fix to the email with
-the bug report. However, for a multi-patch series, it is generally
-best to avoid using In-Reply-To: to link to older versions of the
-series. This way multiple versions of the patch don't become an
-unmanageable forest of references in email clients. If a link is
-helpful, you can use the https://lkml.kernel.org/ redirector (e.g., in
-the cover email text) to link to an earlier version of the patch series.
-
-
-16) Sending ``git pull`` requests
----------------------------------
-
-If you have a series of patches, it may be most convenient to have the
-maintainer pull them directly into the subsystem repository with a
-``git pull`` operation. Note, however, that pulling patches from a developer
-requires a higher degree of trust than taking patches from a mailing list.
-As a result, many subsystem maintainers are reluctant to take pull
-requests, especially from new, unknown developers. If in doubt you can use
-the pull request as the cover letter for a normal posting of the patch
-series, giving the maintainer the option of using either.
-
-A pull request should have [GIT] or [PULL] in the subject line. The
-request itself should include the repository name and the branch of
-interest on a single line; it should look something like::
-
- Please pull from
-
- git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus
-
- to get these changes:
-
-A pull request should also include an overall message saying what will be
-included in the request, a ``git shortlog`` listing of the patches
-themselves, and a ``diffstat`` showing the overall effect of the patch series.
-The easiest way to get all this information together is, of course, to let
-``git`` do it for you with the ``git request-pull`` command.
-
-Some maintainers (including Linus) want to see pull requests from signed
-commits; that increases their confidence that the request actually came
-from you. Linus, in particular, will not pull from public hosting sites
-like GitHub in the absence of a signed tag.
-
-The first step toward creating such tags is to make a GNUPG key and get it
-signed by one or more core kernel developers. This step can be hard for
-new developers, but there is no way around it. Attending conferences can
-be a good way to find developers who can sign your key.
-
-Once you have prepared a patch series in ``git`` that you wish to have somebody
-pull, create a signed tag with ``git tag -s``. This will create a new tag
-identifying the last commit in the series and containing a signature
-created with your private key. You will also have the opportunity to add a
-changelog-style message to the tag; this is an ideal place to describe the
-effects of the pull request as a whole.
-
-If the tree the maintainer will be pulling from is not the repository you
-are working from, don't forget to push the signed tag explicitly to the
-public tree.
-
-When generating your pull request, use the signed tag as the target. A
-command like this will do the trick::
-
- git request-pull master git://my.public.tree/linux.git my-signed-tag
-
-
-REFERENCES
-**********
-
-Andrew Morton, "The perfect patch" (tpp).
- <http://www.ozlabs.org/~akpm/stuff/tpp.txt>
-
-Jeff Garzik, "Linux kernel patch submission format".
- <http://linux.yyz.us/patch-format.html>
-
-Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
- <http://www.kroah.com/log/linux/maintainer.html>
-
- <http://www.kroah.com/log/linux/maintainer-02.html>
-
- <http://www.kroah.com/log/linux/maintainer-03.html>
-
- <http://www.kroah.com/log/linux/maintainer-04.html>
-
- <http://www.kroah.com/log/linux/maintainer-05.html>
-
- <http://www.kroah.com/log/linux/maintainer-06.html>
-
-NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
- <https://lkml.org/lkml/2005/7/11/336>
-
-Kernel Documentation/CodingStyle:
- :ref:`Documentation/CodingStyle <codingstyle>`
-
-Linus Torvalds's mail on the canonical patch format:
- <http://lkml.org/lkml/2005/4/7/183>
-
-Andi Kleen, "On submitting kernel patches"
- Some strategies to get difficult or controversial changes in.
-
- http://halobates.de/on-submitting-patches.pdf
-