1Skia Gold
2=========
3
4Recommended Workflows
5---------------------
6### How to best use Gold for commonly faced problems ###
7
8These instructions will refer to various views which are accessible via the left
9navigation on [gold.skia.org](https://gold.skia.org/).
10View access is public, triage access is granted to
11Skia contributors.  You must be logged in to triage.
12
13Problem #1: As sheriff, I need to triage and “assign” many incoming new images.
14-------------------------------------------------------------------------------
15Solution today:
16
17*   Access the By Blame view to see digests needing triage and associated
18    owners/CLs
19    +   Only untriaged digests will be shown by default
20    +   Blame is not sorted in any particular order
21    +   Digests are clustered by runs and the most minimal set of blame
22
23<img src=BlameView.png style="margin-left:30px" align="left" width="800"/> <br clear="left">
24
25*   Select digests for triage
26    +   Digests will be listed in order with largest difference first
27    +   Click to open the digest view with detailed information
28
29<img src=Digests.png style="margin-left:40px" align="left" width="780"/> <br clear="left">
30
31*   Open bugs for identified owner(s)
32    +   The digest detail view has a link to open a bug from the UI
33    +   Via the Gold UI or when manually entering a bug, copy the full URL of
34        single digest into a bug report
35    +   The URL reference to the digest in Issue Tracker will link the bug to
36        the digest in Gold
37
38<img src="IssueHighlight.png" style="margin-left:60px" align="left" width="720" border=1/> <br clear="left">
39
40<br>
41
42Future improvements:
43
44*   Smarter, more granular blamelist
45
46<br>
47
48Problem #2: As a developer, I need to land a CL that may change many images.
49----------------------------------------------------------------------------
50To find your results:
51
52*   Immediately following commit, access the By Blame view to find untriaged
53    digest groupings associated with your ID
54*   Click on one of the clusters including your CL to triage
55*   Return to the By Blame view to walk through all untriaged digests involving
56    your change
57*   Note:  It is not yet implemented in the UI but possible to filter the view
58    by CL.  Delete hashes in the URL to only include the hash for your CL.
59
60<img src=BlameView.png style="margin-left:30px" align="left" width="800"/> <br clear="left">
61
62To rebaseline images:
63
64*   Access the Ignores view and create a new, short-interval (hours) ignore for
65    the most affected configuration(s)
66
67<img src=Ignores.png style="margin-left:30px" align="left" width="800"/> <br clear="left">
68
69
70*   Click on the Ignore to bring up a search view filtered by the affected
71    configuration(s)
72*   Mark untriaged images as positive (or negative if appropriate)
73*   Follow one of two options for handling former positives:
74    +   Leave former positives as-is and let them fall off with time if there is
75        low risk of recurrence
76    +   Mark former positives as negative if needed to verify the change moving
77        forward
78
79Future improvements:
80
81*   Trybot support prior to commit, with view limited to your CL
82*   Pre-triage prior to commit that will persist when the CL lands
83
84<br>
85
86Problem #3: As a developer or infrastructure engineer, I need to add a new or updated config.
87---------------------------------------------------------------------------------------------
88(ie: new bot, test mode, environment change)
89
90Solution today:
91
92*   Follow the process for rebaselining images:
93    +   Wait for the bot/test/config to be committed and show up in the Gold UI
94    +   Access the Ignores view and create a short-interval ignore for the
95        configuration(s)
96    +   Triage the ignores for that config to identify positive images
97    +   Delete the ignore
98
99Future improvements:
100
101*   Introduction of a new or updated test can make use of try jobs and pre-triage.
102*   New configs may be able to use these features as well.
103
104<br>
105
106Problem #4: As a developer, I need to analyze the details of a particular image digest.
107---------------------------------------------------------------------------------------
108Solution:
109
110*   Access the By Test view
111
112<img src=ByTest.png style="margin-left:30px" align="left" width="800"/> <br clear="left">
113
114*   Click the magnifier to filter by configuration
115*   Access the Cluster view to see the distribution of digest results
116    +   Use control-click to select and do a direct compare between data points
117    +   Click on configurations under “parameters” to highlight data points and
118        compare
119
120<img src=ClusterConfig.png style="margin-left:30px" align="left" width="800"/> <br clear="left">
121
122*   Access the Grid view to see NxN diffs
123
124<img src=Grid.png style="margin-left:30px" align="left" width="800"/> <br clear="left">
125
126*   Access the Dot diagram to see history of commits for the trace
127    +   Each dot represents a commit
128    +   Each line represents a configuration
129    +   Dot colors distinguish between digests
130
131<img src=DotDiagram.png style="margin-left:30px" align="left" width="800"/> <br clear="left">
132
133<br>
134
135Future improvements:
136
137*   Large diff display of image vs image
138
139<br>
140
141Problem #5: As a developer, I need to find results for a particular configuration.
142----------------------------------------------------------------------------------
143Solution:
144
145*   Access the Search view
146*   Select any parameters desired to search across tests
147
148<img src=Search.png style="margin-left:30px" align="left" width="800"/> <br clear="left">
149
150
151