From 55c605562b7f9a87c2a6748557ebe3c81626ceb8 Mon Sep 17 00:00:00 2001
From: Sergey Dolin <dsame@github.com>
Date: Wed, 23 Aug 2023 07:41:56 +0200
Subject: [PATCH] Add advanced Go use cases

---
 docs/adrs/0000-caching-dependencies.md | 106 ++++++++++++++++++++++++-
 1 file changed, 104 insertions(+), 2 deletions(-)

diff --git a/docs/adrs/0000-caching-dependencies.md b/docs/adrs/0000-caching-dependencies.md
index dc8d85837..eac779e65 100644
--- a/docs/adrs/0000-caching-dependencies.md
+++ b/docs/adrs/0000-caching-dependencies.md
@@ -28,7 +28,7 @@ We don't pursue the goal to provide wide customization of caching in scope of `a
 
 # Example of real use-cases
 
- - With cache
+## With cache
 
 ```yml
 steps:
@@ -39,7 +39,7 @@ steps:
     cache: true
 ```
 
- - With cache-dependency-path
+## With cache-dependency-path
 
  ```yml
 steps:
@@ -63,6 +63,108 @@ steps:
         **/go.mod
 ```
 
+ ```yml
+steps:
+- uses: actions/checkout@v3
+- uses: actions/setup-go@v3
+  with:
+    go-version: '18'
+    cache: true
+    cache-dependency-path: **/go.sum
+```
+
+## Multi-target builds
+```yaml
+env:
+  GOOS: ...
+  GOARCH: ...
+
+steps:
+  - run: echo "$GOOS $GOARCH"> /tmp/env
+
+  - uses: actions/setup-go@v4
+    with:
+      cache-dependency-path: go.sum /tmp/env      
+```
+
+## Invalidate cache if source code changes
+```yaml
+- uses: actions/setup-go@v4
+  with:
+    go-version: '1.20'
+    cache-dependency-path: go.sum **/*.go
+```
+
+## Caching with actions/cache
+The caching capabilities of the action are limited for the simplest builds and can be ineffective in the real world
+use cases. If the build requires fine-grained turning the built-in caching should be disabled and
+[actions/cache](https://github.com/actions/cache) should be used.
+
+Here the sample `actions/cache` configuration with the extending options allowing 
+ - configuring paths to cache
+ - have different caches for rare changes dependencies and more often changed intermediate build files
+ - have different caches intermediate build files of different architectures
+ - have custom cache key for parallel builds
+
+```yaml
+build:
+  env:
+   GOOS: ...
+   GOARCH: ...
+
+  steps:
+  - uses: actions/setup-go@v4
+    with:
+      go-version: "1.20.x"
+      cache: false
+
+  - name: Get Go cached paths
+    run: |
+      echo "cache=$(go env GOCACHE)" >> $GITHUB_ENV
+      echo "modcache=$(go env GOMODCACHE)" >> $GITHUB_ENV
+
+  - name: Set up dependencies cache
+    uses: actions/cache@v3
+    with:
+      path: |
+        ${{ env.cache }}
+      key: setup-go-deps-${{ runner.os }}-go-${{ hashFiles('go.sum go.mod') }}
+      restore-keys: |
+        setup-go-deps-${{ runner.os }}-go-
+        
+  - name:
+    run: echo "$GOOS $GOARCH"> /tmp/env
+
+  - name: Set up intermediate built files cache
+    uses: actions/cache@v3
+    with:
+      path: |
+        ${{ env.modcache }}
+      key: setup-go-build-${{ env.GOOS }}-${{ env.GOARCH }}-${{ runner.os }}-go-${{ hashFiles('**/*.go /tmp/env') }}
+      restore-keys: |
+        setup-go-build-${{ env.GOOS }}-${{ env.GOARCH }}
+        
+```
+
+
+## Restore-only caches
+If there are several builds on the same repo it might make sense to create a cache in one build and use it in the
+others. The action [actions/cache/restore](https://github.com/actions/cache/blob/main/restore/README.md#only-restore-cache)
+should be used in this case.
+
+## Include or exclude cached paths
+This advanced use case requires the use of
+[actions/cache](https://github.com/actions/cache/blob/main/examples.md#automatically-detect-cached-paths)
+
+## Generate different caches
+This advanced use case assumes manual definition of cache key and requires the use of
+[actions/cache](https://github.com/actions/cache/blob/main/examples.md#go---modules)
+
+## Parallel builds
+To avoid race conditions during the parallel builds they should either
+[generate their own caches](#generate-different-caches), or create the cache
+for only one build and [restore](#restore-only-caches) that cache in the other builds.
+
 # Release process
 
 As soon as functionality is implemented, we will release minor update of action. No need to bump major version since there are no breaking changes for existing users.