1 <html devsite> 2 <head> 3 <title>Submitting Patches</title> 4 <meta name="project_path" value="/_project.yaml" /> 5 <meta name="book_path" value="/_book.yaml" /> 6 </head> 7 <body> 8 <!-- 9 Copyright 2017 The Android Open Source Project 10 11 Licensed under the Apache License, Version 2.0 (the "License"); 12 you may not use this file except in compliance with the License. 13 You may obtain a copy of the License at 14 15 http://www.apache.org/licenses/LICENSE-2.0 16 17 Unless required by applicable law or agreed to in writing, software 18 distributed under the License is distributed on an "AS IS" BASIS, 19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 20 See the License for the specific language governing permissions and 21 limitations under the License. 22 --> 23 24 25 <p>This page describes the full process of submitting a patch to the AOSP, 26 including 27 reviewing and tracking changes with <a 28 href="https://android-review.googlesource.com/">Gerrit</a>.</p> 29 <h3 id="prerequisites">Prerequisites</h3> 30 <ul> 31 <li> 32 <p>Before you follow the instructions on this page, you need to <a 33 href="/source/initializing.html"> 34 initialize your build environment</a>, <a 35 href="/source/downloading.html">download the source</a>, <a 36 href="https://android.googlesource.com/new-password">create a 37 password</a>, and follow the instructions on the password generator page.</p> 38 </li> 39 <li> 40 <p>For details about Repo and Git, see the <a 41 href="/source/developing.html">Developing</a> section.</p> 42 </li> 43 <li> 44 <p>For information about the different roles you can play within the Android 45 Open Source community, see <a href="/source/roles.html">Project 46 roles</a>.</p> 47 </li> 48 <li> 49 <p>If you plan to contribute code to the Android platform, be sure to read 50 the <a href="/source/licenses.html">AOSP's licensing 51 information</a>.</p> 52 </li> 53 <li> 54 <p>Note that changes to some of the upstream projects used by Android should be 55 made directly to that project, as described in <a 56 href="#upstream-projects">Upstream Projects</a>.</p> 57 </li> 58 </ul> 59 60 <h2 id="for-contributors">For contributors</h2> 61 62 <h3 id="authenticate-with-the-server">Authenticate with the server</h3> 63 <p>Before you can upload to Gerrit, you need to <a 64 href="https://android.googlesource.com/new-password">establish a password</a> 65 that will identify you with the server. Follow the instructions on the password 66 generator page. You need to do this only once. See <a 67 href="/source/downloading.html#using-authentication">Using 68 Authentication</a> for additional details.</p> 69 <h3 id="start-a-repo-branch">Start a repo branch</h3> 70 <p>For each change you intend to make, start a new branch within the relevant 71 git repository:</p> 72 <pre class="devsite-terminal devsite-click-to-copy"> 73 repo start <var>NAME</var> . 74 </pre> 75 <p>You can start several independent branches at the same time in the same 76 repository. The branch NAME is local to your workspace and will not be included 77 on gerrit or the final source tree.</p> 78 <h3 id="make-your-change">Make your change</h3> 79 <p>Once you have modified the source files (and validated them, please) commit 80 the changes to your local repository:</p> 81 <pre class="devsite-click-to-copy"> 82 <code class="devsite-terminal">git add -A</code> 83 <code class="devsite-terminal">git commit -s</code> 84 </pre> 85 <p>Provide a detailed description of the change in your commit message. This 86 description will be pushed to the public AOSP repository, so please follow our 87 guidelines for writing changelist descriptions: </p> 88 <ul> 89 90 <li> 91 <p>Start with a one-line summary (50 characters maximum), followed by a 92 blank line. 93 This format is used by git and gerrit for various displays.</p> 94 </li> 95 96 <li> 97 <p>Starting on the third line, enter a longer description, which must 98 hard-wrap at 72 characters maximum. This description should focus on what 99 issue the change solves, and how it solves it. The second part is somewhat 100 optional when implementing new features, though desirable.</p> 101 </li> 102 <li> 103 <p>Include a brief note of any assumptions or background information that 104 may be important when another contributor works on this feature next year.</p> 105 </li> 106 </ul> 107 108 <p>Here is an example commit message:</p> 109 <pre class="devsite-click-to-copy">short description on first line 110 111 more detailed description of your patch, 112 which is likely to take up multiple lines. 113 </pre> 114 115 <p>A unique change ID and your name and email as provided during <code>repo 116 init</code> will be automatically added to your commit message. </p> 117 118 <h3 id="upload-to-gerrit">Upload to gerrit</h3> 119 <p>Once you have committed your change to your personal history, upload it 120 to gerrit with</p> 121 <pre class="devsite-terminal devsite-click-to-copy"> 122 repo upload 123 </pre> 124 <p>If you have started multiple branches in the same repository, you will 125 be prompted to select which one(s) to upload.</p> 126 <p>After a successful upload, repo will provide you the URL of a new page on 127 <a href="https://android-review.googlesource.com/">Gerrit</a>. Visit this 128 link to view 129 your patch on the review server, add comments, or request specific reviewers 130 for your patch.</p> 131 <h3 id="uploading-a-replacement-patch">Uploading a replacement patch</h3> 132 <p>Suppose a reviewer has looked at your patch and requested a small 133 modification. You can amend your commit within git, which will result in a 134 new patch on gerrit with the same change ID as the original.</p> 135 <aside class="note"><b>Note:</b> If you have made other commits since uploading this patch, 136 you will need to manually move your git HEAD.</aside> 137 <pre class="devsite-click-to-copy"> 138 <code class="devsite-terminal">git add -A</code> 139 <code class="devsite-terminal">git commit --amend</code> 140 </pre> 141 <p>When you upload the amended patch, it will replace the original on gerrit 142 and in your local git history.</p> 143 144 <h3 id="resolving-sync-conflicts">Resolving sync conflicts</h3> 145 <p>If other patches are submitted to the source tree that conflict with 146 yours, you will need to rebase your patch on top of the new HEAD of the 147 source repository. The easy way to do this is to run</p> 148 <pre class="devsite-terminal devsite-click-to-copy"> 149 repo sync 150 </pre> 151 <p>This command first fetches the updates from the source server, then 152 attempts to automatically rebase your HEAD onto the new remote HEAD.</p> 153 <p>If the automatic rebase is unsuccessful, you will have to perform a 154 manual rebase.</p> 155 <pre class="devsite-terminal devsite-click-to-copy"> 156 repo rebase 157 </pre> 158 <p>Using <code>git mergetool</code> may help you deal with the rebase 159 conflict. Once you have successfully merged the conflicting files,</p> 160 <pre class="devsite-terminal devsite-click-to-copy"> 161 git rebase --continue 162 </pre> 163 <p>After either automatic or manual rebase is complete, run <code>repo 164 upload</code> to submit your rebased patch.</p> 165 166 <h3 id="after-a-submission-is-approved">After a submission is approved</h3> 167 <p>After a submission makes it through the review and verification process, 168 Gerrit automatically merges the change into the public repository. Other 169 users will be able to run <code>repo sync</code> to pull the update into 170 their local client.</p> 171 172 <h2 id="for-reviewers-and-verifiers">For reviewers and verifiers</h2> 173 174 <h3 id="reviewing-a-change">Reviewing a change</h3> 175 <p>If you are assigned to be the Approver for a change, you need to determine 176 the following:</p> 177 <ul> 178 <li> 179 <p>Does this change fit within this project's stated purpose?</p> 180 </li> 181 <li> 182 <p>Is this change valid within the project's existing architecture?</p> 183 </li> 184 <li> 185 <p>Does this change introduce design flaws that will cause problems in 186 the future?</p> 187 </li> 188 <li> 189 <p>Does this change follow the best practices that have been established 190 for this project?</p> 191 </li> 192 <li> 193 <p>Is this change a good way to perform the described function?</p> 194 </li> 195 <li> 196 <p>Does this change introduce any security or instability risks?</p> 197 </li> 198 </ul> 199 <p>If you approve of the change, mark it with LGTM ("Looks Good to Me") 200 within Gerrit.</p> 201 <h3 id="verifying-a-change">Verifying a change</h3> 202 <p>If you are assigned to be the Verifier for a change, you need to do the 203 following:</p> 204 <ul> 205 <li> 206 <p>Patch the change into your local client using one of the Download 207 commands.</p> 208 </li> 209 <li> 210 <p>Build and test the change.</p> 211 </li> 212 <li> 213 <p>Within Gerrit use Publish Comments to mark the commit as "Verified" or 214 "Fails," and add a message explaining what problems were identified.</p> 215 </li> 216 </ul> 217 218 <h3 id="downloading-changes-from-gerrit">Downloading changes from Gerrit</h3> 219 <p>A submission that has been verified and merged will be downloaded with 220 the next <code>repo sync</code>. If you wish to download a specific change 221 that has not yet been approved, run</p> 222 <pre class="devsite-terminal devsite-click-to-copy"> 223 repo download <var>TARGET CHANGE</var> 224 </pre> 225 <p>where TARGET is the local directory into which the change should be 226 downloaded and CHANGE is the 227 change number as listed in <a 228 href="https://android-review.googlesource.com/">Gerrit</a>. For more 229 information, 230 see the <a href="/source/using-repo.html">Repo reference</a>.</p> 231 <h3 id="how-do-i-become-a-verifier-or-approver">How do I become a Verifier 232 or Approver?</h3> 233 <p>In short, contribute high-quality code to one or more of the Android 234 projects. 235 For details about the different roles in the Android Open Source community and 236 who plays them, see <a href="/source/roles.html">Project 237 Roles</a>.</p> 238 <h3 id="diffs-and-comments">Diffs and comments</h3> 239 <p>To open the details of the change within Gerrit, click on the "Id number" 240 or "Subject" of a change. To compare the established code with the updated 241 code, click the file name under "Side-by-side diffs."</p> 242 <h3 id="adding-comments">Adding comments</h3> 243 <p>Anyone in the community can use Gerrit to add inline comments to code 244 submissions. A good comment will be relevant to the line or section of code 245 to which it is attached in Gerrit. It might be a short and constructive 246 suggestion about how a line of code could be improved, or it might be an 247 explanation from the author about why the code makes sense the way it is.</p> 248 <p>To add an inline comment, double-click the relevant line of the code 249 and write your comment in the text box that opens. When you click Save, 250 only you can see your comment.</p> 251 <p>To publish your comments so that others using Gerrit will be able to see 252 them, click the Publish Comments button. Your comments will be emailed to 253 all relevant parties for this change, including the change owner, the patch 254 set uploader (if different from the owner), and all current reviewers.</p> 255 <p><a name="upstream-projects"></a></p> 256 <h2 id="upstream-projects">Upstream Projects</h2> 257 <p>Android makes use of a number of other open source projects, such as the 258 Linux kernel and WebKit, as described in 259 <a href="/source/code-lines.html">Codelines, Branches, and 260 Releases</a>. For most projects under <code>external/</code>, changes should 261 be made upstream and then the Android maintainers informed of the new upstream 262 release containing these changes. It may also be useful to upload patches 263 that move us to track a new upstream release, though these can be difficult 264 changes to make if the project is widely used within Android like most of the 265 larger ones mentioned below, where we tend to upgrade with every release.</p> 266 <p>One interesting special case is bionic. Much of the code there is from BSD, 267 so unless the change is to code that's new to bionic, we'd much rather see an 268 upstream fix and then pull a whole new file from the appropriate BSD. (Sadly 269 we have quite a mix of different BSDs at the moment, but we hope to address 270 that in future, and get into a position where we track upstream much more 271 closely.)</p> 272 <h3 id="icu4c">ICU4C</h3> 273 <p>All changes to the ICU4C project at <code>external/icu4c</code> should 274 be made upstream at 275 <a href="http://site.icu-project.org/">icu-project.org/</a>. 276 See <a href="http://site.icu-project.org/bugs">Submitting ICU Bugs and 277 Feature Requests</a> for more.</p> 278 279 <h3 id="llvmclangcompiler-rt">LLVM/Clang/Compiler-rt</h3> 280 <p>All changes to LLVM-related projects (<code>external/clang</code>, 281 <code>external/compiler-rt</code>, 282 <code>external/llvm</code>) should be made upstream at 283 <a href="http://llvm.org/">llvm.org/</a>.</p> 284 285 <h3 id="mksh">mksh</h3> 286 <p>All changes to the MirBSD Korn Shell project at <code>external/mksh</code> 287 should be made upstream 288 either by sending an email to miros-mksh on the mirbsd.org domain (no 289 subscription 290 required to submit there) or (optionally) at <a 291 href="https://launchpad.net/mksh">Launchpad</a>. 292 </p> 293 <h3 id="openssl">OpenSSL</h3> 294 <p>All changes to the OpenSSL project at <code>external/openssl</code> 295 should be made upstream at 296 <a href="http://www.openssl.org">openssl.org</a>.</p> 297 <h3 id="v8">V8</h3> 298 <p>All changes to the V8 project at <code>external/v8</code> should be 299 submitted upstream at 300 <a href="https://code.google.com/p/v8">code.google.com/p/v8</a>. See <a 301 href="https://code.google.com/p/v8/wiki/Contributing">Contributing to V8</a> 302 for details.</p> 303 <h3 id="webkit">WebKit</h3> 304 <p>All changes to the WebKit project at <code>external/webkit</code> should 305 be made 306 upstream at <a href="http://www.webkit.org">webkit.org</a>. The process 307 begins by filing a WebKit bug. 308 This bug should use <code>Android</code> for the <code>Platform</code> 309 and <code>OS</code> 310 fields only if the bug is specific to Android. Bugs are far more likely to 311 receive the reviewers' 312 attention once a proposed fix is added and tests are included. See 313 <a href="http://webkit.org/coding/contributing.html">Contributing Code to 314 WebKit</a> for details.</p> 315 <h3 id="zlib">zlib</h3> 316 <p>All changes to the zlib project at <code>external/zlib</code> should be 317 made upstream at 318 <a href="http://zlib.net">zlib.net</a>.</p> 319 320 321 </body> 322 </html> 323
