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