managing chromes use section of docs

site/dev/chrome/blink.md

Index: site/dev/chrome/blink.md
diff --git a/site/dev/chrome/blink.md b/site/dev/chrome/blink.md
new file mode 100644
index 0000000000000000000000000000000000000000..10ca14047217dc1c832aa0afae8cdd0c35ca3ca7
--- /dev/null
+++ b/site/dev/chrome/blink.md
@@ -0,0 +1,112 @@
+How to land Skia changes that change Blink layout test results
+==============================================================
+
+Changes that affect a small number of layout test results
+---------------------------------------------------------
+Changes affecting fewer than ~20 layout tests can be rebaselined without special
+coordination with the Blink gardener using these steps:
+
+### Rebaseline Layout Tests
+
+#### First create a Chromium bug:
+* Go to (http://crbug.com)
+  Make sure you’re logged in with your Chromium credentials
+* Click “New Issue”
+* Summary: “Skia image rebaseline”
+* Description: List DEPS roll #, helpful message about what changed \(e\.g\.,
+“Changes to how lighting is scaled in Skia revision ###### changed the following
+images:”\), & layout tests affected
+    * You should copy the list of affected from stdio of the failing bot
+* Status: Assigned
+* Owner: fmalita@
+* cc: reed@, bsalomon@, robertphillips@ & developer responsible for changes
+* Labels: OS\-All & Cr\-Blink\-LayoutTests
+
+#### Edit skia/skia\_test\_expectations\.txt
+* Add # comment about what has changed \(I usually paraphrase the crbug text\)
+* Add line\(s\) like this after the comment:
+  crbug\.com/<bug\#youjustcreated> foo/bar/test\-name\.html \[ ImageOnlyFailure \]
+
+#### Commit the changes and fire off new try bots
+  You usually only need to fire off the layout bots.

[bungeman-skia, 2015/02/18 15:58:36]

This is good as far as it goes, I suppose, but it's too bad that it doesn't go
on to state how to actually remove the suppression. Just suppressing means you
aren't done yet.

The benefit to this setup is that Skia doesn't need code suppressions. The
downside now is that you cannot use the auto rebaseline bot (as [
NeedsRebaseline ] in this file will not be rebaselined). As a result, the
baselines need to be manually updated in Blink, and then these suppressions
removed from Chromium. This was useful in the days before the auto rebaseline
bot when you'd have to update the baselines manually anyway, but these days this
may actually be more (and easier to get wrong) work.

+
+
+Changes that affect a large number of test results 
+--------------------------------------------------
+Where a 'large number' or 'many' means more than about 20.  
+Follow the instructions below:
+
+In the following the term 'code suppression' means a build flag \(a\.k\.a\. define\).
+Such code suppressions should be given a name with the form SK\_IGNORE\_xxx\_FIX.
+
+There are dependency revisions which must be updated in this
+process. Updating a dependency revision is called a 'roll'. 
+There are two different rolls which concern this process, each of which happens
+via an Auto Roll Bot multiple times per day, and can also be done manually:
+    
+  * Skia roll into Chromium. See
+(https://chromium.googlesource.com/chromium/src/+log/master/DEPS) and search for
+skia\-deps\-roller.
+  * Blink roll into Chromium. See
+(https://chromium.googlesource.com/chromium/src/+log/master/DEPS) and search for
+blink\-deps\-roller.
+
+### Setup
+#### Code suppression does not yet exist \- Direct method 
+1. Make a change in Skia which will change many Blink layout tests.
+2. Put the change behind a code suppression.  
+3. Check in the change to the Skia repository.
+4. Manually roll Skia or append the autoroll with the code suppression to 
+Chromium's 'skia/skia\_common\.gypi'  
+5. Add code suppression to Blink's 'public/blink\_skia\_config\.gyp'.  
+6. Wait for Blink roll into Chromium.
+7. Remove code suppression from Chromium's 'skia/skia\_common\.gypi'.  
+
+#### Code suppression does not yet exist \- Alternate method
+1. Add code suppression to Blink's 'public/blink\_skia\_config\.gyp' before making code
+changes in Skia.  
+2. Make a change in Skia which will change many Blink layout tests.
+3. Put the change behind a code suppression.
+4. Wait for Blink roll into Chromium.
+5. Check in the change to the Skia repository.
+6. Wait for Skia roll into Chromium.
+ 
+#### Code suppression exists in header
+1. Remove code suppression from header file in Chromium and add code suppression to
+Chromium's 'skia/skia\_common\.gypi'.  
+The code suppression cannot be in a header file and a defined in a gyp file at the 
+same time or a multiple definition warning will be treated as an error and break 
+the Chromium build.
+2. Add code suppression to Blink's 'public/blink\_skia\_config\.gyp'.
+3. Wait for Blink roll into Chromium.
+4. Remove code suppression from Chromium's 'skia/skia\_common\.gypi'.
+
+### Rebaseline

[bungeman-skia, 2015/02/18 15:58:36]

This is more or less right (I think this section was originally written by
fmalita), but it is a bit hand-wavy (Rebaseline like any Blink rebaseline?) and
a bit out of date now.

I think the more modern version of this is to:

Create a CL removing the code suppression from Blink's
public/blink_skia_config.gyp while simultaneously adding [ NeedsRebaseline ]
lines to blink's LayoutTests/TestExpectations file. Then the auto rebaseline bot
will take care of the work of actually checking in the new images. This is
generally acceptable for up to 600 or so rebaselined images. Above that you
might still use [ NeedsRebaseline ], but it's best to coordinate with the
gardener/sheriff. This should go through the CQ cleanly.

Basically, this paragraph should probably replace most of 2 and the first
sentence of 3. I'd keep the rest of the warning in 3 (starting with 'Be
careful...').

+1. Choose a time when the Blink tree is likely to be quiet. Avoid PST afternoons in
+particular. The bigger the change, the more important this is. Regardless,
+determine who the Blink gardener is and notify them. You will be making the
+Chromium\.WebKit tree very red for an extended period, and the gardener needs to
+know that they are not expected to fix it.  
+2. Remove code suppression from Blink's public/blink\_skia\_config\.gyp. It is 
+recommended, but not essential, that you prepare new baselines for at least one 
+platform to commit when you commit the blink\_skia\_config\.gyp change, although only 
+try this if you are familiar with new\-run\-webkit\-tests and the parameters for 
+controlling baseline generation. Mark the change as an unreviewed Skia build change.
+3. Rebaseline like any Blink rebaseline. Be careful with tests that are already
+failing or flakey. These may or may not need to be rebaselined and flakey tests
+should not be removed from TestExpectations regardless. In such cases revert the
+TestExpectations changes before committing.  
+4. If you are not the one handling the cleanup step, please open a Skia Issue of the 
+form
+Title: "Remove code suppression SK\_IGNORE\_xxx\_FIX\."
+Comment: "Code suppression SK\_IGNORE\_xxx\_FIX rebaselined with Blink revision
+123456\." and assign it to the individual responsible for the cleanup step.
+ 
+### Cleanup
+1. Wait for Blink roll into Chromium, so that Chromium is using the new Skia code
+and new Blink baselines.  
+2. Remove the now unused old code from Skia and any defines which were introduced 
+to suppress the new code.
+3. Check in the cleanup change to the Skia repository.
+4. Wait for Skia roll into Chromium.
+