Revamp CI/CD cache reference docs

doc/ci/caching/index.md

@@ -62,50 +62,64 @@ For runners to work with caches efficiently, you must do one of the following:
   share a common network-mounted directory to store the cache. This directory should use NFS or something similar.
   These runners must be in autoscale mode.
 
-### Share caches between jobs in the same branch
-
-To have jobs for each branch use the same cache, define a cache with the `key: ${CI_COMMIT_REF_SLUG}`:
-
-```yaml
-cache:
-  key: ${CI_COMMIT_REF_SLUG}
-```
+## Use multiple caches
 
-This configuration prevents you from accidentally overwriting the cache. However, the
-first pipeline for a merge request is slow. The next time a commit is pushed to the branch, the
-cache is re-used and jobs run faster.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32814) in GitLab 13.10.
+> - [Feature Flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321877), in GitLab 13.12.
 
-To enable per-job and per-branch caching:
+You can have a maximum of four caches:
 
 ```yaml
-cache:
-  key: "$CI_JOB_NAME-$CI_COMMIT_REF_SLUG"
+test-job:
+  stage: build
+  cache:
+    - key:
+        files:
+          - Gemfile.lock
+      paths:
+        - vendor/ruby
+    - key:
+        files:
+          - yarn.lock
+      paths:
+        - .yarn-cache/
+  script:
+    - bundle install --path=vendor
+    - yarn install --cache-folder .yarn-cache
+    - echo Run tests...
 ```
 
-To enable per-stage and per-branch caching:
+If multiple caches are combined with a [Fallback cache key](#fallback-cache-key),
+the fallback cache is fetched every time a cache is not found.
 
-```yaml
-cache:
-  key: "$CI_JOB_STAGE-$CI_COMMIT_REF_SLUG"
-```
+## Fallback cache key
 
-### Share caches across jobs in different branches
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1534) in GitLab Runner 13.4.
 
-To share a cache across all branches and all jobs, use the same key for everything:
+You can use the `$CI_COMMIT_REF_SLUG` [predefined variable](../variables/predefined_variables.md)
+to specify your [`cache:key`](../yaml/README.md#cachekey). For example, if your
+`$CI_COMMIT_REF_SLUG` is `test` you can set a job to download cache that's tagged with `test`.
 
-```yaml
-cache:
-  key: one-key-to-rule-them-all
-```
+If a cache with this tag is not found, you can use `CACHE_FALLBACK_KEY` to
+specify a cache to use when none exists.
 
-To share caches between branches, but have a unique cache for each job:
+In the following example, if the `$CI_COMMIT_REF_SLUG` is not found, the job uses the key defined
+by the `CACHE_FALLBACK_KEY` variable:
 
 ```yaml
-cache:
-  key: ${CI_JOB_NAME}
+variables:
+  CACHE_FALLBACK_KEY: fallback-key
+
+job1:
+  script:
+    - echo
+  cache:
+    key: "$CI_COMMIT_REF_SLUG"
+    paths:
+      - binaries/
 ```
 
-### Disable cache for specific jobs
+## Disable cache for specific jobs
 
 If you have defined the cache globally, it means that each job uses the
 same definition. You can override this behavior per-job, and if you want to
@@ -116,7 +130,7 @@ job:
   cache: {}
 ```
 
-### Inherit global configuration, but override specific settings per job
+## Inherit global configuration, but override specific settings per job
 
 You can override cache settings without overwriting the global cache by using
 [anchors](../yaml/README.md#anchors). For example, if you want to override the
@@ -124,7 +138,7 @@ You can override cache settings without overwriting the global cache by using
 
 ```yaml
 cache: &global_cache
-  key: ${CI_COMMIT_REF_SLUG}
+  key: $CI_COMMIT_REF_SLUG
   paths:
     - node_modules/
     - public/
@@ -150,6 +164,49 @@ PHP packages, Ruby gems, Python libraries, and others can all be cached.
 
 For more examples, check out our [GitLab CI/CD templates](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates).
 
+### Share caches between jobs in the same branch
+
+To have jobs for each branch use the same cache, define a cache with the `key: $CI_COMMIT_REF_SLUG`:
+
+```yaml
+cache:
+  key: $CI_COMMIT_REF_SLUG
+```
+
+This configuration prevents you from accidentally overwriting the cache. However, the
+first pipeline for a merge request is slow. The next time a commit is pushed to the branch, the
+cache is re-used and jobs run faster.
+
+To enable per-job and per-branch caching:
+
+```yaml
+cache:
+  key: "$CI_JOB_NAME-$CI_COMMIT_REF_SLUG"
+```
+
+To enable per-stage and per-branch caching:
+
+```yaml
+cache:
+  key: "$CI_JOB_STAGE-$CI_COMMIT_REF_SLUG"
+```
+
+### Share caches across jobs in different branches
+
+To share a cache across all branches and all jobs, use the same key for everything:
+
+```yaml
+cache:
+  key: one-key-to-rule-them-all
+```
+
+To share caches between branches, but have a unique cache for each job:
+
+```yaml
+cache:
+  key: $CI_JOB_NAME
+```
+
 ### Cache Node.js dependencies
 
 If your project is using [npm](https://www.npmjs.com/) to install the Node.js
@@ -166,7 +223,7 @@ image: node:latest
 
 # Cache modules in between jobs
 cache:
-  key: ${CI_COMMIT_REF_SLUG}
+  key: $CI_COMMIT_REF_SLUG
   paths:
     - .npm/
 
@@ -193,7 +250,7 @@ image: php:7.2
 
 # Cache libraries in between jobs
 cache:
-  key: ${CI_COMMIT_REF_SLUG}
+  key: $CI_COMMIT_REF_SLUG
   paths:
     - vendor/
 
@@ -262,7 +319,7 @@ image: ruby:2.6
 
 # Cache gems in between builds
 cache:
-  key: ${CI_COMMIT_REF_SLUG}
+  key: $CI_COMMIT_REF_SLUG
   paths:
     - vendor/ruby
 
@@ -287,7 +344,7 @@ cache:
   key:
     files:
       - Gemfile.lock
-    prefix: ${CI_JOB_NAME}
+    prefix: $CI_JOB_NAME
   paths:
     - vendor/ruby
 

doc/development/pipelines.md

@@ -559,7 +559,7 @@ request, be sure to start the `dont-interrupt-me` job before pushing.
    - `.qa-cache`
    - `.yarn-cache`
    - `.assets-compile-cache` (the key includes `${NODE_ENV}` so it's actually two different caches).
-1. These cache definitions are composed of [multiple atomic caches](../ci/yaml/README.md#multiple-caches).
+1. These cache definitions are composed of [multiple atomic caches](../ci/caching/index.md#use-multiple-caches).
 1. Only 6 specific jobs, running in 2-hourly scheduled pipelines, are pushing (i.e. updating) to the caches:
    - `update-setup-test-env-cache`, defined in [`.gitlab/ci/rails.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/rails.gitlab-ci.yml).
    - `update-gitaly-binaries-cache`, defined in [`.gitlab/ci/rails.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/rails.gitlab-ci.yml).