Vim documentation: diff
5 stars based on
This document contains a large number of suggestions in a relatively terse format. In general, use of git will make your life as a kernel developer easier. If you do not have a repository with the current kernel source handy, use git to obtain one. Note, however, re patch docs explain diff*binary options you may not want to develop against the mainline tree directly. Most subsystem re patch docs explain diff*binary options run their own trees and want to see patches prepared against those trees.
It is still possible to download kernel releases via tarballs as described in the next sectionbut that is the hard way to do kernel development. If you must generate your patches by hand, use diff -up or diff -uprN to create patches. All changes to the Linux kernel occur in the form of patches, as generated by 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. 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 diff 1to 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 3 Separate your changes.
This will facilitate review by other kernel developers, very important if you want your patch re patch docs explain diff*binary options. Whether your patch is a one-line bug re patch docs explain diff*binary options or 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 re patch docs explain diff*binary options read past the first paragraph. Straight up crashes and lockups are pretty convincing, but not all bugs are re patch docs explain diff*binary options blatant. Even if the problem was spotted during code review, describe the impact you think it can have on users.
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. 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.
See 15 Explicit In-Reply-To headers. Solve only one problem per patch. See 3 Separate your changes. When you submit or resubmit a patch or patch series, include the complete patch description and justification for it.
This benefits both the maintainers and reviewers. Describe your changes in imperative mood, e. 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: 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.
Please also include the oneline summary of the commit, to make it easier for reviewers to know what it is about. 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.
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:. For example, if your changes include both bug fixes and performance enhancements for a re patch docs explain diff*binary options driver, separate those changes into two or more patches.
On the other hand, if you make a single change to numerous files, group those changes re patch docs explain diff*binary options 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. 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. 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. 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. If you cannot find a maintainer for the subsystem you are working on, Andrew Morton akpm linux-foundation.
You should also normally choose at least one mailing list to receive a copy of your patch set. Please do not spam unrelated lists, though. Many kernel-related lists are hosted on vger. There are kernel-related lists hosted elsewhere re patch docs explain diff*binary options well, though. Linus Torvalds is the final arbiter of all changes accepted into the Linux kernel.
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. 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:. Note, however, that some subsystem maintainers want to come to their own conclusions on which patches should go to re patch docs explain diff*binary options stable trees.
The networking maintainer, in particular, would rather not see individual developers adding lines like the above to their patches. User-space API changes should also be copied to linux-api vger. Linus and other kernel developers need to be able to read and comment on the changes you are submitting. 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.
If your mailer is mangling patches then someone may ask you to re-send them using MIME. Large changes are not appropriate for mailing lists, and some maintainers. If your patch, uncompressed, exceeds 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 kB, it almost certainly re patch docs explain diff*binary options to be broken up anyway. 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. 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.
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.
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 re patch docs explain diff*binary options simple: Some people also put extra tags at the end. If you stick strictly to rule cyou should ask the submitter re patch docs explain diff*binary options rediff, but this is a totally counter-productive waste of time and energy.
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. 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. 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.
Whatever the format, this information provides re patch docs explain diff*binary options valuable help to people tracking your trees, and to people trying to troubleshoot bugs in your tree. 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: It is a record that the acker has at least reviewed the patch re patch docs explain diff*binary options has indicated acceptance.
For example, if a patch affects multiple subsystems and has an Acked-by: Judgement should be used here.