1 <!-- 2 Copyright 2010 The Android Open Source Project 3 4 Licensed under the Apache License, Version 2.0 (the "License"); 5 you may not use this file except in compliance with the License. 6 You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10 Unless required by applicable law or agreed to in writing, software 11 distributed under the License is distributed on an "AS IS" BASIS, 12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 See the License for the specific language governing permissions and 14 limitations under the License. 15 --> 16 17 # Submitting Patches # 18 19 This page describes the full process of submitting a patch to the AOSP, including reviewing and tracking changes with Gerrit. 20 21 ## Prerequisites ## 22 23 - Before you follow the instructions on this page, you will need to set up your 24 local working environment and get the Android source files. For instructions, 25 follow the "Getting Started" section [here](downloading.html). 26 27 - For details about Repo and Git, see [Version Control](version-control.html). 28 29 - For information about the different roles you can play within the Android 30 Open Source community, see [Project roles](/source/roles.html). 31 32 - If you plan to contribute code to the Android platform, be sure to read 33 the [AOSP's licensing information](/source/licenses.html). 34 35 - Note that changes to some of the upstream projects used by Android should be 36 made directly to that project, as described in [Upstream Projects](#upstream-projects). 37 38 # For contributors # 39 40 ## Start a repo branch ## 41 42 For each change you intend to make, start a new branch within the relevant git repository: 43 44 $ repo start NAME 45 46 You can start several independent branches at the same time in the same repository. The branch NAME is local to your workspace and will not be included on gerrit or the final source tree. 47 48 ## Make your change ## 49 50 Once you have modified the source files (and validated them, please) commit the changes to your local repository: 51 52 $ git add -A 53 $ git commit -s 54 55 Provide a detailed description of the change in your commit message. This description will be pushed to the public AOSP repository, so please follow our guidelines for writing changelist descriptions: 56 57 - Start with a one-line summary (60 characters max), followed by a blank line. This format is used by git and gerrit for various displays. 58 59 short description on first line 60 61 more detailed description of your patch, 62 which is likely to take up multiple lines. 63 64 - The description should focus on what issue it solves, and how it solves it. The second part is somewhat optional when implementing new features, though desirable. 65 66 - Include a brief note of any assumptions or background information that may be important when another contributor works on this feature next year. 67 68 A unique change ID and your name and email as provided during `repo init` will be automatically added to your commit message. 69 70 ## Upload to gerrit ## 71 72 Once you have committed your change to your personal history, upload it to gerrit with 73 74 $ repo upload 75 76 If you have started multiple branches in the same repository, you will be prompted to select which one(s) to upload. 77 78 After a successful upload, repo will provide you the URL of a new page on [r.android.com](http://review.source.android.com). Visit this link to view your patch on the review server, add comments, or request specific reviewers for your patch. 79 80 ## Uploading a replacement patch ## 81 82 Suppose a reviewer has looked at your patch and requested a small modification. You can amend your commit within git, which will result in a new patch on gerrit with the same change ID as the original. 83 84 *Note that if you have made other commits since uploading this patch, you will need to manually move your git HEAD.* 85 86 $ git add -A 87 $ git commit --amend 88 89 When you upload the amended patch, it will replace the original on gerrit and in your local git history. 90 91 ## Resolving sync conflicts ## 92 93 If other patches are submitted to the source tree that conflict with yours, you will need to rebase your patch on top of the new HEAD of the source repository. The easy way to do this is to run 94 95 $ repo sync 96 97 This command first fetches the updates from the source server, then attempts to automatically rebase your HEAD onto the new remote HEAD. 98 99 If the automatic rebase is unsuccessful, you will have to perform a manual rebase. 100 101 $ git rebase master 102 103 Using `git mergetool` may help you deal with the rebase conflict. Once you have successfully merged the conflicting files, 104 105 $ git rebase --continue 106 107 After either automatic or manual rebase is complete, run `repo upload` to submit your rebased patch. 108 109 ## After a submission is approved ## 110 111 After a submission makes it through the review and verification process, Gerrit automatically merges the change into the public repository. The change will now be visible in gitweb, and others users will be able to run `repo sync` to pull the update into their local client. 112 113 # For reviewers and verifiers # 114 115 ## Reviewing a change ## 116 117 If you are assigned to be the Approver for a change, you need to determine the following: 118 119 - Does this change fit within this project's stated purpose? 120 121 - Is this change valid within the project's existing architecture? 122 123 - Does this change introduce design flaws that will cause problems in the future? 124 125 - Does this change follow the best practices that have been established for this project? 126 127 - Is this change a good way to perform the described function? 128 129 - Does this change introduce any security or instability risks? 130 131 If you approve of the change, mark it with LGTM ("Looks Good to Me") within Gerrit. 132 133 ## Verifying a change ## 134 135 If you are assigned to be the Verifier for a change, you need to do the following: 136 137 - Patch the change into your local client using one of the Download commands. 138 139 - Build and test the change. 140 141 - Within Gerrit use Publish Comments to mark the commit as "Verified" or "Fails," and add a message explaining what problems were identified. 142 143 ## Downloading changes from Gerrit ## 144 145 A submission that has been verified and merged will be downloaded with the next `repo sync`. If you wish to download a specific change that has not yet been approved, run 146 147 $ repo download TARGET CHANGE 148 149 where TARGET is the local directory into which the change should be downloaded and CHANGE is the 150 change number as listed in [Gerrit](https://review.source.android.com/). For more information, 151 see the [Repo reference](/source/using-repo.html). 152 153 ## How do I become a Verifier or Approver? ## 154 155 In short, contribute high-quality code to one or more of the Android projects. 156 For details about the different roles in the Android Open Source community and 157 who plays them, see [Project Roles](/source/roles.html). 158 159 ## Diffs and comments ## 160 161 To open the details of the change within Gerrit, click on the "Id number" or "Subject" of a change. To compare the established code with the updated code, click the file name under "Side-by-side diffs." 162 163 ## Adding comments ## 164 165 Anyone in the community can use Gerrit to add inline comments to code submissions. A good comment will be relevant to the line or section of code to which it is attached in Gerrit. It might be a short and constructive suggestion about how a line of code could be improved, or it might be an explanation from the author about why the code makes sense the way it is. 166 167 To add an inline comment, double-click the relevant line of the code and write your comment in the text box that opens. When you click Save, only you can see your comment. 168 169 To publish your comments so that others using Gerrit will be able to see them, click the Publish Comments button. Your comments will be emailed to all relevant parties for this change, including the change owner, the patch set uploader (if different from the owner), and all current reviewers. 170 171 ## Using GitWeb to track patch histories ## 172 173 To view snapshots of the files that are in the public Android repositories and view file histories, use the [Android instance of GitWeb](http://android.git.kernel.org/). 174 175 <a name="upstream-projects"></a> 176 177 # Upstream Projects # 178 179 Android makes use of a number of other open-source projects, such as the Linux kernel and WebKit, as described in 180 [Branches and Releases](/source/code-lines.html). For the upstream projects detailed below, changes should be made directly upstream. Such changes will be incorporated into the Android tree as part of the usual process of pulling these projects. 181 182 ## WebKit ## 183 184 All changes to the WebKit project at `external/webkit` should be made 185 upstream at [webkit.org](http://www.webkit.org). The process begins by filing a WebKit bug. 186 This bug should use `Android` for the `Platform` and `OS` 187 fields only if the bug is specific to Android. Bugs are far more likely to receive the reviewers' 188 attention once a proposed fix is added and tests are included. See 189 [Contributing Code to WebKit](http://webkit.org/coding/contributing.html) for details. 190 191 ## V8 ## 192 193 All changes to the V8 project at `external/v8` should be submitted upstream at 194 [code.google.com/p/v8](http://code.google.com/p/v8). See [Contributing to V8](http://code.google.com/p/v8/wiki/Contributing) 195 for details. 196 197
