About this guide

This guide is designed to give you an idea of how to write linux-wireless patches.

Subscribe to this page

We would like to ask Linux-wireless developers to subscribe to this page on the wiki. Any new policies and best practices on patching to linux-wireless will be posted here.

Prior to sending patches

Please DO NOT PGP sign patches sent to linux-wireless. The reason is that signing patches will encapsulate them into MIME and thereby mangle the patch. Also, please note that we prefer patches inline rather than attachments.

Where Maintainers contains the list of maintainers for the piece of code you are patching. Other Developers in this case can be a list of developers who you think may like to review this patch or who changed the code you are working on recently.

Checking state of patches from patchwork

All wireless patches are tracked in linux-wireless patchwork project (only exception being ath10k which has its own ath10k patchwork project). From patchwork you can check the state of the patch and to whom it is assigned. Here's a quick link to see all the patches, no matter what's the state:

Always avoid contacting maintainers directly, they get way too much email already. Instead use the link above to find your patch and see the status. Only in last resort contact the maintainers, and do that by replying to your own patch and ask for status.

Different patchwork states and their meanings:

New: No action haven't taken yet, expect maybe assigned to a correct maintainer.

Under Review: The maintainer is waiting review comments from others.

Accepted: The maintainer has applied the patch to his/her tree.

Rejected: The maintainer rejected the patch, reasons stated in an email.

Changes Requested: Either the maintainer or a reviewer requested changes in the patch. The maintainer expects the patch author to submit a new version.

Deferred: The maintainer has postponed the review of the patch for some reason, for example due to lack of time, patch being to controversial or something else. Patch author doesn't need to take any action, the maintainer will revisit the patch in a later time.

Awaiting Upstream: The patch depends on an another patch from a different tree, for example a wireless driver needing a specific mac80211 patch to implement a new feature.

RFC: The patch is sent as Request For Comments. The maintainer expects the patch author to submit a new version.

Superseded: There's a new version of the patch available, the maintainer has skipped this version.

Not Applicable: The patch is either not part of wireless subsystem or it will be applied via different trees (for example net-next or driver maintainer trees). The patch is considered as dropped from now on and needs to be resubmitted for the maintainer to reconsider it.

Subject

If what you are sending is a patch you can use a subject as follows:

[PATCH] subsystem: fix foo and optimize bar

In case of wireless patches the subsystem can for example be mac80211, cfg80211 or the name of the driver, for example ath9k. There's an easy way to check with git what prefix you should use:

Always increase the version number, no matter how small the change is. The maintainers focus on the latest version and ignore the older versions. Make sure that the maintainers don't need to guess what version he should take, that just creates problems.

Then sending a new version of the patch always add a change log, either after the --- line (three dashes) or in the cover letter.

If a patch in a bigger patchset changes resubmit the whole patchset, even the patches which have not changes. The maintainers look at patchsets as a complete unit, usually they do not want to take patches individually from a patchset.

Sending large patches or multiple patches

You should only send a large patch if your patch does one specific task, or a few of them if they are easy to review. If your work consists of multiple tasks you must split your tasks into separate patches. Each patch must address a small set of tasks to help the maintainers with revision. The rule of thumb here is if you read your patch and if its not clear what the patch is doing then better break it down into separate patches. Patches should also be run through scripts/checkpatch.pl.

If you are sending multiple patches which depend on each other you can use this format for the subjects:

On the e-mail with subject, “[PATCH 0/4] driver_name: introduce foo and bar”, you would give a brief overview of all the changes. No patch should be included in that e-mail, and as that e-mail will not end up in the change logs it should not contain anything that should be archived, only a rough overview over the purpose of the patch set, no in-depth description which should be in the changelog for each patch.

Format of patches

We prefer patches to be inline-text at the end of the body of the e-mail. You can use git-diff or the like to generate the patch. Additionally note that we prefer to apply patches with -p1. A header as follows is then acceptable:

Patch tags

In order to track who worked on a patch and released the source code under the appropriate licenses used, patch tags are used to track of provenance of patches. This also helps developers review who was in the line of a patch work, who submitted it, and who reviewed it. This information is available from the git-log. We currently use, Signed-off-by, Acked-by, Cc, Reviewed-by and Tested-by.

Please note that since you are submitting patches inline, after the Signed-off-by: lines, you must put ---, that is three dashes. Example:

Please also read the official Linux SubmittingPatches documentation, especially Section 12 and the Developer's Certificate of Origin. Do not submit patches unless you have read, understood and agreed to the certificate.

Examples of a patches

Below are a few examples of a patches. Only the header is provided for long patches.

Frequent problems in patch submissions

Patch version missing

If you send a new version of the patch or patchset you should always add a version number. The first version does not need to be shown but starting from second version the version number must be available: