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