Google Git
Sign in
android / kernel / common / android-mainline / . / README.md
blob: 91cb840af72d5c919f408c308799e3f4a835ce88 [file] [log] [blame] [view]
Todd Kjosf8978f42019-10-24 17:07:24 -0700[diff] [blame]1# How do I submit patches to Android Common Kernels
2
31. BEST: Make all of your changes to upstream Linux. If appropriate, backport to the stable releases.
4 These patches will be merged automatically in the corresponding common kernels. If the patch is already
5 in upstream Linux, post a backport of the patch that conforms to the patch requirements below.
Todd Kjos2f886a62019-12-12 11:36:29 -0800[diff] [blame]6 - Do not send patches upstream that contain only symbol exports. To be considered for upstream Linux,
7additions of `EXPORT_SYMBOL_GPL()` require an in-tree modular driver that uses the symbol -- so include
8the new driver or changes to an existing driver in the same patchset as the export.
9 - When sending patches upstream, the commit message must contain a clear case for why the patch
10is needed and beneficial to the community. Enabling out-of-tree drivers or functionality is not
Eric Biggersc0a79472023-07-08 00:10:20 +0000[diff] [blame]11a persuasive case.
Todd Kjosf8978f42019-10-24 17:07:24 -0700[diff] [blame]12
132. LESS GOOD: Develop your patches out-of-tree (from an upstream Linux point-of-view). Unless these are
14 fixing an Android-specific bug, these are very unlikely to be accepted unless they have been
15 coordinated with kernel-team@android.com. If you want to proceed, post a patch that conforms to the
16 patch requirements below.
17
18# Common Kernel patch requirements
19
Carlos Llamas3b3f4742021-04-07 23:11:23 +0000[diff] [blame]20- All patches must conform to the Linux kernel coding standards and pass `scripts/checkpatch.pl`
Todd Kjosf8978f42019-10-24 17:07:24 -0700[diff] [blame]21- Patches shall not break gki_defconfig or allmodconfig builds for arm, arm64, x86, x86_64 architectures
22(see https://source.android.com/setup/build/building-kernels)
23- If the patch is not merged from an upstream branch, the subject must be tagged with the type of patch:
24`UPSTREAM:`, `BACKPORT:`, `FROMGIT:`, `FROMLIST:`, or `ANDROID:`.
25- All patches must have a `Change-Id:` tag (see https://gerrit-review.googlesource.com/Documentation/user-changeid.html)
26- If an Android bug has been assigned, there must be a `Bug:` tag.
27- All patches must have a `Signed-off-by:` tag by the author and the submitter
28
29Additional requirements are listed below based on patch type
30
31## Requirements for backports from mainline Linux: `UPSTREAM:`, `BACKPORT:`
32
33- If the patch is a cherry-pick from Linux mainline with no changes at all
34 - tag the patch subject with `UPSTREAM:`.
Matthias Maennich21ec9a72019-12-03 08:03:21 +0000[diff] [blame]35 - add upstream commit information with a `(cherry picked from commit ...)` line
Yongqin Liu8ad9aa942024-07-25 12:43:19 +0800[diff] [blame]36 - if applicable, prefer to cherry-pick the commit from the corresponding LTS branch.
Yongqin Liu6dfa5532024-07-25 13:02:51 +0800[diff] [blame]37 - append new signature tags (e.g. `Bug:`, `Change-Id:`, etc.) at the end to keep the
38 chronological order.
Todd Kjosf8978f42019-10-24 17:07:24 -0700[diff] [blame]39 - Example:
40 - if the upstream commit message is
41```
42 important patch from upstream
43
44 This is the detailed description of the important patch
45
46 Signed-off-by: Fred Jones <[email protected]>
47```
Todd Kjos21578d52019-12-12 10:57:32 -0800[diff] [blame]48>- then Joe Smith would upload the patch for the common kernel as
Todd Kjosf8978f42019-10-24 17:07:24 -0700[diff] [blame]49```
50 UPSTREAM: important patch from upstream
51
52 This is the detailed description of the important patch
53
54 Signed-off-by: Fred Jones <[email protected]>
55
56 Bug: 135791357
57 Change-Id: I4caaaa566ea080fa148c5e768bb1a0b6f7201c01
Matthias Maennich21ec9a72019-12-03 08:03:21 +0000[diff] [blame]58 (cherry picked from commit c31e73121f4c1ec41143423ac6ce3ce6dafdcec1)
Todd Kjosf8978f42019-10-24 17:07:24 -0700[diff] [blame]59 Signed-off-by: Joe Smith <[email protected]>
60```
61
62- If the patch requires any changes from the upstream version, tag the patch with `BACKPORT:`
63instead of `UPSTREAM:`.
64 - use the same tags as `UPSTREAM:`
Matthias Maennich21ec9a72019-12-03 08:03:21 +0000[diff] [blame]65 - add comments about the changes under the `(cherry picked from commit ...)` line
Todd Kjosf8978f42019-10-24 17:07:24 -0700[diff] [blame]66 - Example:
67```
68 BACKPORT: important patch from upstream
69
70 This is the detailed description of the important patch
71
72 Signed-off-by: Fred Jones <[email protected]>
73
74 Bug: 135791357
75 Change-Id: I4caaaa566ea080fa148c5e768bb1a0b6f7201c01
Matthias Maennich21ec9a72019-12-03 08:03:21 +0000[diff] [blame]76 (cherry picked from commit c31e73121f4c1ec41143423ac6ce3ce6dafdcec1)
Matthias Maennichcba941a2020-01-08 15:11:06 +0000[diff] [blame]77 [joe: Resolved minor conflict in drivers/foo/bar.c ]
Todd Kjosf8978f42019-10-24 17:07:24 -0700[diff] [blame]78 Signed-off-by: Joe Smith <[email protected]>
79```
80
81## Requirements for other backports: `FROMGIT:`, `FROMLIST:`,
82
83- If the patch has been merged into an upstream maintainer tree, but has not yet
84been merged into Linux mainline
85 - tag the patch subject with `FROMGIT:`
Alistair Delvadc7d8262025-08-22 10:41:47 -0700[diff] [blame]86 - add info on where the patch came from as `(cherry picked from commit <sha1> <repo> <branch>)`.
87This must be a branch on a tree which is normally merged into Linus's tree and is not rebased. For
88example, don't use `linux-next` which is rebased and never directly merged into Linus's tree, but
89you *can* use SHAs from `net` *or* `net-next`, which are merged into Linus's tree at various points
90in the release.
Todd Kjosf8978f42019-10-24 17:07:24 -0700[diff] [blame]91 - if changes were required, use `BACKPORT: FROMGIT:`
92 - Example:
93 - if the commit message in the maintainer tree is
94```
95 important patch from upstream
96
97 This is the detailed description of the important patch
98
99 Signed-off-by: Fred Jones <[email protected]>
100```
Todd Kjos21578d52019-12-12 10:57:32 -0800[diff] [blame]101>- then Joe Smith would upload the patch for the common kernel as
Todd Kjosf8978f42019-10-24 17:07:24 -0700[diff] [blame]102```
103 FROMGIT: important patch from upstream
104
105 This is the detailed description of the important patch
106
107 Signed-off-by: Fred Jones <[email protected]>
108
109 Bug: 135791357
110 (cherry picked from commit 878a2fd9de10b03d11d2f622250285c7e63deace
111 https://git.kernel.org/pub/scm/linux/kernel/git/foo/bar.git test-branch)
112 Change-Id: I4caaaa566ea080fa148c5e768bb1a0b6f7201c01
113 Signed-off-by: Joe Smith <[email protected]>
114```
115
116
117- If the patch has been submitted to LKML, but not accepted into any maintainer tree
118 - tag the patch subject with `FROMLIST:`
Matthias Maennich511b8512019-10-28 23:46:05 +0000[diff] [blame]119 - add a `Link:` tag with a link to the submittal on lore.kernel.org
Todd Kjos9794e7e2020-05-01 13:43:26 -0700[diff] [blame]120 - add a `Bug:` tag with the Android bug (required for patches not accepted into
121a maintainer tree)
Todd Kjosf8978f42019-10-24 17:07:24 -0700[diff] [blame]122 - if changes were required, use `BACKPORT: FROMLIST:`
123 - Example:
124```
125 FROMLIST: important patch from upstream
126
127 This is the detailed description of the important patch
128
129 Signed-off-by: Fred Jones <[email protected]>
130
131 Bug: 135791357
132 Link: https://lore.kernel.org/lkml/[email protected]/
133 Change-Id: I4caaaa566ea080fa148c5e768bb1a0b6f7201c01
134 Signed-off-by: Joe Smith <[email protected]>
135```
136
Greg Kroah-Hartman748f0752025-01-24 07:42:15 +0100[diff] [blame]137- If a patch has been submitted to the community, but rejected, do NOT use the
138 `FROMLIST:` tag to try to hide this fact. Use the `ANDROID:` tag as
139 described below as this must be considered as an Android-specific submission,
140 not an upstream submission as the community will not accept these changes
141 as-is.
142
Todd Kjosf8978f42019-10-24 17:07:24 -0700[diff] [blame]143## Requirements for Android-specific patches: `ANDROID:`
144
145- If the patch is fixing a bug to Android-specific code
146 - tag the patch subject with `ANDROID:`
147 - add a `Fixes:` tag that cites the patch with the bug
148 - Example:
149```
150 ANDROID: fix android-specific bug in foobar.c
151
152 This is the detailed description of the important fix
153
154 Fixes: 1234abcd2468 ("foobar: add cool feature")
155 Change-Id: I4caaaa566ea080fa148c5e768bb1a0b6f7201c01
156 Signed-off-by: Joe Smith <[email protected]>
157```
158
159- If the patch is a new feature
160 - tag the patch subject with `ANDROID:`
161 - add a `Bug:` tag with the Android bug (required for android-specific features)
162
Aaliyah Merchantda4a3a62025-09-10 07:00:37 -0700[diff] [blame]163## Requirements for revert patches:
164
165- Add a reason for the revert
166- Do not delete or modify the revert information that is generated when using
167`git revert`
168- If modifications have been made after creating the revert, include a list of
169these in the commit message
170- Example:
171```
172 Revert "ANDROID: fix android-specific bug in foobar.c"
173
174 This reverts commit a57a7913f53e34c8a8d905444b126b3316146e69.
175
176 Reason for revert: Breaks a lot of internal tests
177
178 Additional modifications: Resolved merge conflicts
179
180 Bug: 135791357
181 Change-Id: I4caaaa566ea080fa148c5e768bb1a0b6f7201c01
182 Signed-off-by: Joe Smith <[email protected]>
183```