docs: clarify the process of managing the golden images cache

Author: Westbrook

.circleci/config.yml

@@ -43,6 +43,7 @@ commands:
                 type: string
         steps:
             - restore_cache:
+                  name: Restore Golden Images Cache
                   keys:
                       - v1-golden-images-<< parameters.regression_color >>-<< parameters.regression_scale >>-b9e157e40b4274683707eccf7f8d400ed4c719bc
                       - v1-golden-images-master-<< parameters.regression_color >>-<< parameters.regression_scale >>-
@@ -52,12 +53,12 @@ commands:
                   command: cp -RT test/visual/screenshots-current/ci test/visual/screenshots-baseline/ci && exit 1
             - save_cache:
                   when: on_fail
-                  name: Force Update Regression Cache
+                  name: Build Golden Images Revision Cache
                   paths:
                       - test/visual/screenshots-baseline/ci
                   key: v1-golden-images-<< parameters.regression_color >>-<< parameters.regression_scale >>-{{ .Revision }}
             - save_cache:
-                  name: Build Branch Cache
+                  name: Build Golden Images Branch Cache
                   paths:
                       - test/visual/screenshots-baseline/ci
                   key: v1-golden-images-{{ .Branch }}-<< parameters.regression_color >>-<< parameters.regression_scale >>-{{ epoch }}

README.md

@@ -89,29 +89,18 @@ Visual testing is run against the stories in Storybook, and stories added there
 
 #### Keeping CI Assets Up-to-date
 
-If you find the `visual-*` jobs failing on CircleCI for reasons that you expect (you've updated the Spectrum CSS dependencies, you've added new tests, etc.) then you will need to update the golden images cache before your build will pass. Said update is a multi-step process that allows you to update the golden images for your branch without disrupting other work going on in the repo while also preparing for the reality that CircleCI caches are only guaranteed for up to 30 days. All of the following changes bellow will be made against the CircleCI config file found at `.circleci/config.yml` and will need to be committed to your branch individually in order to have their desired effect.
+If you find the `visual-*` jobs failing on CircleCI for reasons that you expect (you've updated the Spectrum CSS dependencies, you've added new tests, etc.) then you will need to update the golden images cache key before your build will pass. Said update is a two-step process that allows you to update the golden images for your branch without disrupting other work going on in the repo while also preparing for the reality that CircleCI caches are only guaranteed for up to 30 days, but if you've already run a failing build, you're half way there!
 
-1. Update the `force_update_regression_cache` parameter in the `run-regressions` command to `true` in order to build a new cache:
+Your failing branch will have created a new cache with a key of `v1-golden-images-<< parameters.regression_color >>-<< parameters.regression_scale >>-{{ .Revision }}`. In `.circleci/config.yml`, you will use that to update the cache that is restored at the beginning of the `run-regressions`, at least for the next 30 days. Using the revision number outlined in the `Build Golden Images Revision Cache` step of your failing build, update the first cache key listed in the `Restore Golden Images Cache` steps that appears as follows:
 
 ```
-            force_update_regression_cache:
-                type: boolean
-                default: true
+- restore_cache:
+    name: Restore Golden Images Cache
+    keys:
+        - v1-golden-images-<< parameters.regression_color >>-<< parameters.regression_scale >>-${REVISION_NUMBER}
 ```
 
-This will build a new cache with key `v1-golden-images-<< parameters.regression_color >>-<< parameters.regression_scale >>-{{ .Revision }}` that will be used in the following step.
-
-2. Once the previous build has run and the new cache has been created, you'll be able to update the key of the cache loaded into the `visual-*` steps with the revision number from the previouos build:
-
-```
-            - restore_cache:
-                  keys:
-                      - v1-golden-images-<< parameters.regression_color >>-<< parameters.regression_scale >>-
-```
-
-Be sure to return the value for `force_update_regression_cache` back to `false` when committing this change and pushing it to remote.
-
-At this point your branch should now be able to pass the visual regression tests by loading the golden images from the correct cache. The fact that this revision based cache will expire after 30 days is overcome by the fallback key of `v1-golden-images-master-<< parameters.regression_color >>-<< parameters.regression_scale >>-` which will address the latest cache created by the `master` branch at all times.
+With this update, your branch should now be able to pass the visual regression tests by loading the golden images from the new cache. The fact that this revision based cache will expire after 30 days is overcome by the fallback key of `v1-golden-images-master-<< parameters.regression_color >>-<< parameters.regression_scale >>-` which will address the latest cache created by the `master` branch whenever the specifically requested revision cache is not available.
 
 ## Benchmarking