diff --git a/docs/adrs/0000-caching-dependencies.md b/docs/adrs/0000-caching-dependencies.md index dc8d85837..9b37540e4 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,109 @@ 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 + id: find-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.