Development: How to submit patches

This article provides an overview for submitting patches against the V4L-DVB source code (for either new or existing kernel driver modules and/or documentation), and as well as for the dvb-apps source. For general references in regards as to how to develop support for a particular device or in writing a new device driver, see here.

Patch Preparation

For V4L-DVB driver modules and/or documentation, patches should be created against the master V4L-DVB mercurial tree; for instructions on obtaining and building these sources, see the "How to Obtain, Build and Install V4L-DVB Device Drivers" article. Similarly, for submissions related to the dvb-apps, one should patch against the dvb-apps mercurial tree.

Post your patches to the linux-media mailing list for review and testing. Subscription to the mailing list is recommended, though it is not required.

Follow the guidelines in Submitting Patches (cf. jgarzik's version), including:

• Verify best-practice kernel coding style
• Use [PATCH] in the subject line to get attention ... Note: the patchwork tool (discussed below) actually does NOT rely upon this label for detection of patches; rather, patchwork utilizes logic algorithms to detect for the presence of a patch within an email message. That being the case, the "[PATCH]" flag serves only to alert your human counterparts/peers on the mailing list of your submission
• Explain what the patch does and to what hardware it applies. Note: All comments you add on your patch will be part of the commit message (except for the meta-tags)
• Document your work where appropriate (i.e. in the form of patches to the Documentation/video4linux or Documentation/dvb files)
• Add a Signed-off-by: Your name <name@yoursite.com> as a Developer's Certificate of Origin 1.1
• Send the patch inline, not as an attachment (unless otherwise asked to do so) ... patches presented in the form of inline text in the body of an email are easier to deal with from the perspective of a peer review process (for more information, see the /usr/src/linux/Documentation/email-clients.txt file; a current copy of which can also be found online here).
• Note: various web mail interfaces seem to be problematic for patch submissionn, in that:
  • they may break the patch (e.g. line wrapping it) or
  • in the case where you have sent the patch as an attachment, the emailer may use the wrong mime encoding type ... (web mailers often wrongly use "application/octet-stream" for diffs, whereas the proper type is "text/x-patch" ... Note: the patchwork tool (discussed below) is robust in that it supports both mime types "text/x-patch" and "text/plain", but if the emailer has sent it with a different type, the attachment will be disregarded/discarded.

Hint: There is also a checklist for patch submission

Firmware submission

Some drivers may require firmwares in order to properly work. In such cases, if the firmware is not already available, some sort of procedure is needed for other users to use the driver.

To follow the Open Source spirit, and to help debugging some troubles, the better is if the firmware is submitted as a source code, under GPL, but unfortunately very few firmwares are submitted with sources. Yet, as submitting firmwares with a source code is not a mandatory requirement, they can be provided on a binary format. However, for it to be available at the Linux distributions, it is required that each firmware should be provided with the distribution and redistribution rights, given by the device or by the chipset manufacturer.

In order to submit a firmware, an email from the vendor or from the chipset manufacturer to [Linux Media Mailing List - LMML] and/or to [Mauro (the V4L/DVB Maintainer)] should be sent containing the license terms and the firmware files. If the licensing is ok, the firmware files will be added at the [V4L/DVB linux-firmware git tree] and submitted to the upstream linux-firmware tree.

There is no unique model for firmware licensing, but there are some examples at [WHENCE] file and at the several LICENCE files at the tree. The most common models for non GPL'd firmwares are:

• firmware model1
• firmware model2

After you've Submitted: What happens Next?

In conjunction with the move to the new Linux-media mailing list, V4L-DVB is now using the Patchwork tool for aggregating patches sent into the list (you can read more about it here). In the past, it was, unfortunately, not uncommon for patches to be overlooked and become lost on the V4L-DVB mailing lists; thus making the adoption of the patchwork tool a very welcome addition. So, provided you have correctly submitted your patch (as discussed above), the steps towards having your code adopted will have automatically been put into motion. You can, of course, check to see the status of your submission from the Patchwork webpage. If patchwork has not picked up your patch (after a reasonable period of time has elapsed), it is quite probable that your submission was incorrect for some reason; please review the information contained in the above section and try again.

After being picked up by patchwork, the first thing you should expect next is that a code review will be performed, and often this is by various parties. This may lead to a series of requests for you to fix any observed problems and require you to then resubmit your work, by repeating the same steps outlined above, until everyone is happy with the submission. In other words: wash, rinse, repeat ;)

Then, when your patch is accepted, it will initially be applied to the main V4L-DVB mercurial tree. Once tested and integrated, such patches are later merged into a git tree by the V4L-DVB maintainer and, upon request, periodically pulled by Linus into one of his own git trees in an intermediate step towards final inclusion into the Linux kernel.