From d7192f47c4ec1d58bfbd3316fbb21efee67c65a8 Mon Sep 17 00:00:00 2001
From: Akihiro Suda <akihiro.suda.cz@hco.ntt.co.jp>
Date: Sun, 17 Sep 2023 03:14:45 +0900
Subject: [PATCH] README.md: update

Signed-off-by: Akihiro Suda <akihiro.suda.cz@hco.ntt.co.jp>
---
 README.md | 84 ++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 56 insertions(+), 28 deletions(-)

diff --git a/README.md b/README.md
index a145944..2cb915a 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,35 @@
-# The BuildKit Cache Dance
+# The BuildKit Cache Dance: save `RUN --mount=type=cache` caches on GitHub Actions
 
-Workaround buildkit/buildx's lack of integrated caching solution.
+The BuildKit Cache Dance allows saving [`RUN --mount=type=cache`](https://docs.docker.com/build/guide/mounts/#add-a-cache-mount)
+caches on GitHub Actions.
 
-Forked from [`overmindtech/buildkit-cache-dance`](https://github.com/overmindtech/buildkit-cache-dance/tree/306d31a77191f643c0c4a95083f36c6ddccb4a16).
+Use cases:
+- apt-get (`/var/cache/apt`, `/var/lib/apt`)
+- Go (`/root/.cache/go-build`)
+- etc.
 
+This [`reproducible-containers/buildkit-cache-dance`](https://github.com/reproducible-containers/buildkit-cache-dance) action was forked from
+[`overmindtech/buildkit-cache-dance`](https://github.com/overmindtech/buildkit-cache-dance/tree/306d31a77191f643c0c4a95083f36c6ddccb4a16)
+(archived on September 2023).
+This action be used for "non-reproducible" containers too.
+
+## Examples
+### apt-get
+Dockerfile:
+```dockerfile
+FROM ubuntu:22.04
+ENV DEBIAN_FRONTEND=noninteractive
+RUN \
+  --mount=type=cache,target=/var/cache/apt,sharing=locked \
+  --mount=type=cache,target=/var/lib/apt,sharing=locked \
+  rm -f /etc/apt/apt.conf.d/docker-clean && \
+  echo 'Binary::apt::APT::Keep-Downloaded-Packages "true";' >/etc/apt/apt.conf.d/keep-cache && \
+  apt-get update && \
+  apt-get install -y gcc
 ```
+
+Action:
+```yaml
 ---
 name: Build
 on: push
@@ -12,50 +37,49 @@ on: push
 jobs:
   build:
     name: Build
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v2
-
-      - name: Docker meta
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v2
+      - uses: docker/metadata-action@v4
         id: meta
-        uses: docker/metadata-action@v4
         with:
           images: YOUR_IMAGE
-          tags: |
-            type=ref,event=branch
-            type=ref,event=pr
-            type=semver,pattern={{version}}
-            type=semver,pattern={{major}}.{{minor}}
-
-      - name: Go Build Cache for Docker
+      - name: Cache var-cache-apt
         uses: actions/cache@v3
         with:
-          path: go-build-cache
-          key: ${{ runner.os }}-go-build-cache-${{ hashFiles('**/go.sum') }}
-
-      - name: inject go-build-cache into docker
+          path: var-cache-apt
+          key: var-cache-apt-${{ hashFiles('Dockerfile') }}
+      - name: Cache var-lib-apt
+        uses: actions/cache@v3
+        with:
+          path: var-lib-apt
+          key: var-lib-apt-${{ hashFiles('Dockerfile') }}
+      - name: inject var-cache-apt into docker
         uses: reproducible-containers/buildkit-cache-dance@v2.1.2
         with:
-          cache-source: go-build-cache
-
+          cache-source: var-cache-apt
+          cache-target: /var/cache/apt
+      - name: inject var-lib-apt into docker
+        uses: reproducible-containers/buildkit-cache-dance@v2.1.2
+        with:
+          cache-source: var-lib-apt
+          cache-target: /var/lib/apt
       - name: Build and push
         uses: docker/build-push-action@v3
         with:
           context: .
           cache-from: type=gha
           cache-to: type=gha,mode=max
-          file: build/package/Dockerfile
+          file: Dockerfile
           push: ${{ github.event_name != 'pull_request' }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
-          platforms: linux/amd64,linux/arm64
 ```
 
-Thanks to [Alexander Pravdin](https://github.com/speller) for the basic idea in [this comment](https://github.com/moby/buildkit/issues/1512).
+Real-world examples:
+- <https://github.com/rootless-containers/slirp4netns/blob/v1.2.2/.github/workflows/release.yaml#L18-L36>
+- <https://github.com/containers/fuse-overlayfs/blob/40e0f3c/.github/workflows/release.yaml#L17-L36>
 
 ## Releases
 ### v1
@@ -69,3 +93,7 @@ See the [`releases/v1`](https://github.com/reproducible-containers/buildkit-cach
 
 ### v2
 v2 is composed of the single `reproducible-containers/buildkit-cache-dance` action.
+
+## Acknowledgement
+- Thanks to [Alexander Pravdin](https://github.com/speller) for the basic idea in [this comment](https://github.com/moby/buildkit/issues/1512).
+- Thanks to the authors of the original [`overmindtech/buildkit-cache-dance`](https://github.com/overmindtech/buildkit-cache-dance).