1 How to submit a patch 2 ===================== 3 4 5 Configure git 6 ------------- 7 8 <!--?prettify lang=sh?--> 9 10 git config --global user.name "Your Name" 11 git config --global user.email you (a] example.com 12 13 Making changes 14 -------------- 15 16 First create a branch for your changes: 17 18 <!--?prettify lang=sh?--> 19 20 git config branch.autosetuprebase always 21 git checkout -b my_feature origin/master 22 23 After making your changes, create a commit 24 25 <!--?prettify lang=sh?--> 26 27 git add [file1] [file2] ... 28 git commit 29 30 If your branch gets out of date, you will need to update it: 31 32 <!--?prettify lang=sh?--> 33 34 git pull 35 python tools/git-sync-deps 36 37 Adding a unit test 38 ------------------ 39 40 If you are willing to change Skia codebase, it's nice to add a test at the same 41 time. Skia has a simple unittest framework so you can add a case to it. 42 43 Test code is located under the 'tests' directory. 44 45 See [Writing Unit and Rendering Tests](../testing/tests) for details. 46 47 Unit tests are best, but if your change touches rendering and you can't think of 48 an automated way to verify the results, consider writing a GM test or a new page 49 of SampleApp. Also, if your change is the GPU code, you may not be able to write 50 it as part of the standard unit test suite, but there are GPU-specific testing 51 paths you can extend. 52 53 Submitting a patch 54 ------------------ 55 56 For your code to be accepted into the codebase, you must complete the 57 [Individual Contributor License 58 Agreement](http://code.google.com/legal/individual-cla-v1.0.html). You can do 59 this online, and it only takes a minute. If you are contributing on behalf of a 60 corporation, you must fill out the [Corporate Contributor License 61 Agreement](http://code.google.com/legal/corporate-cla-v1.0.html) 62 and send it to us as described on that page. Add your (or your organization's) 63 name and contact info to the AUTHORS file as a part of your CL. 64 65 Now that you've made a change and written a test for it, it's ready for the code 66 review! Submit a patch and getting it reviewed is fairly easy with depot tools. 67 68 Use git-cl, which comes with [depot 69 tools](http://sites.google.com/a/chromium.org/dev/developers/how-tos/install-depot-tools). 70 For help, run git-cl help. 71 72 ### Find a reviewer 73 74 Ideally, the reviewer is someone who is familiar with the area of code you are 75 touching. If you have doubts, look at the git blame for the file to see who else 76 has been editing it. 77 78 ### Uploading changes for review 79 80 Skia uses the Gerrit code review tool. Skia's instance is [skia-review](http://skia-review.googlesource.com). 81 Use git cl to upload your change: 82 83 <!--?prettify lang=sh?--> 84 85 git cl upload 86 87 You may have to enter a Google Account username and password to authenticate 88 yourself to Gerrit. A free gmail account will do fine, or any 89 other type of Google account. It does not have to match the email address you 90 configured using `git config --global user.email` above, but it can. 91 92 The command output should include a URL, similar to 93 (https://skia-review.googlesource.com/c/4559/), indicating where your changelist 94 can be reviewed. 95 96 ### Request review 97 98 Go to the supplied URL or go to the code review page and select the **Your** 99 dropdown and click on **Changes**. Select the change you want to submit for 100 review and click **Reply**. Enter at least one reviewer's email address. Now 101 add any optional notes, and send your change off for review by clicking on 102 **Send**. Unless you send your change to reviewers, no one will know to look 103 at it. 104 105 _Note_: If you don't see editing commands on the review page, click **Sign in** 106 in the upper right. _Hint_: You can add -r reviewer (a] example.com --send-mail to 107 send the email directly when uploading a change using git-cl. 108 109 110 The review process 111 ------------------ 112 113 If you submit a giant patch, or do a bunch of work without discussing it with 114 the relevant people, you may have a hard time convincing anyone to review it! 115 116 Code reviews are an important part of the engineering process. The reviewer will 117 almost always have suggestions or style fixes for you, and it's important not to 118 take such suggestions personally or as a commentary on your abilities or ideas. 119 This is a process where we work together to make sure that the highest quality 120 code gets submitted! 121 122 You will likely get email back from the reviewer with comments. Fix these and 123 update the patch set in the issue by uploading again. The upload will explain 124 that it is updating the current CL and ask you for a message explaining the 125 change. Be sure to respond to all comments before you request review of an 126 update. 127 128 If you need to update code the code on an already uploaded CL, simply edit the 129 code, commit it again locally, and then run git cl upload again e.g. 130 131 echo "GOATS" > whitespace.txt 132 git add whitespace.txt 133 git commit -m 'add GOATS fix to whitespace.txt' 134 git cl upload 135 136 Once you're ready for another review, use **Reply** again to send another 137 notification (it is helpful to tell the review what you did with respect to each 138 of their comments). When the reviewer is happy with your patch, they will 139 approve your change by setting the Code-Review label to "+1". 140 141 _Note_: As you work through the review process, both you and your reviewers 142 should converse using the code review interface, and send notes. 143 144 Once your change has received an approval, you can click the "Submit to CQ" 145 button on the codereview page and it will be committed on your behalf. 146 147 Once your commit has gone in, you should delete the branch containing your change: 148 149 git checkout -q origin/master 150 git branch -D my_feature 151 152 153 Final Testing 154 ------------- 155 156 Skia's principal downstream user is Chromium, and any change to Skia rendering 157 output can break Chromium. If your change alters rendering in any way, you are 158 expected to test for and alleviate this. (You may be able to find a Skia team 159 member to help you, but the onus remains on each individual contributor to avoid 160 breaking Chrome. 161 162 ### Evaluating Impact on Chromium 163 164 Keep in mind that Skia is rolled daily into Blink and Chromium. Run local tests 165 and watch canary bots for results to ensure no impact. If you are submitting 166 changes that will impact layout tests, follow the guides below and/or work with 167 your friendly Skia-Blink engineer to evaluate, rebaseline, and land your 168 changes. 169 170 Resources: 171 172 [How to land Skia changes that change Blink layout test results](../chrome/layouttest) 173 174 If you're changing the Skia API, you may need to make an associated change in Chromium. 175 If you do, please follow these instructions: [Landing Skia changes which require Chrome changes](../chrome/changes) 176 177 178 Check in your changes 179 --------------------- 180 181 ### Non-Skia-committers 182 183 If you already have committer rights, you can follow the directions below to 184 commit your change directly to Skia's repository. 185 186 If you don't have committer rights in https://skia.googlesource.com/skia.git ... 187 first of all, thanks for submitting your patch! We really appreciate these 188 submissions. After receiving an approval from a committer, you will be able to 189 click the "Submit to CQ" button and submit your patch via the commit queue. 190 191 In special instances, a Skia committer may assist you in landing the change 192 by uploading a new codereview containing your patch (perhaps with some small 193 adjustments at his/her discretion). If so, you can mark your change as 194 "Abandoned", and update it with a link to the new codereview. 195 196 ### Skia committers 197 * tips on how to apply an externally provided patch are [here](./patch) 198 * when landing externally contributed patches, please note the original 199 contributor's identity (and provide a link to the original codereview) in the commit message 200 201 git-cl will squash all your commits into a single one with the description you used when you uploaded your change. 202 203 ~~~~ 204 git cl land 205 ~~~~ 206 207 or 208 209 ~~~~ 210 git cl land -c 'Contributor Name <email (a] example.com>' 211 ~~~~ 212
