calculate-cache.sh: add some descriptions

Signed-off-by: Norio Nomura <norio.nomura@gmail.com>

Author: norio-nomura

hack/calculate-cache.sh

@@ -6,6 +6,34 @@
 
 # usage: [DEBUG=1] ./hack/calculate-cache.sh
 # DEBUG=1 will save the collected information in .calculate-cache-collected-info-{before,after}.yaml
+#
+# This script does:
+# 1. extracts `runs_on` and `template` from workflow file (.github/workflows/test.yml)
+# 2. check each template for image and nerdctl
+# 3. detect size of image and nerdctl (responses from remote are cached for faster iteration)
+# 4. print content size, actual cache size (if available), by cache key
+# 
+# The major differences for reducing cache usage are as follows:
+# - it is now cached `~/.cache/lima/download/by-url-sha256/$sha256` instead of caching `~/.cache/lima/download`
+# - the cache keys are now based on the image digest and nerdctl digest instead of the template file's hash
+# - enables the use of cache regardless of the operating system used to execute CI.
+#
+# The script requires the following commands:
+# - gh: GitHub CLI.
+#   Using to get the cache information
+# - jq: Command-line JSON processor
+#   Parse the workflow file and print runs-on and template.
+#   Parse output from gh cache list
+#   Calculate the expected content size, actual cached size, and cache-keys used.
+# - limactl: lima CLI.
+#   Using to validate the template file for getting nerdctl location and digest.
+# - sha256sum: Print or check SHA256 (256-bit) checksums
+# - xxd: make a hexdump or do the reverse.
+#   Using to simulate the 'hashFile()' function in the workflow.
+# - yq: Command-line YAML processor.
+#   Parse the template file for image and nerdctl location, digest, and size.
+#   Parse the cache response file for the cache.
+#   Convert the collected information to JSON.
 
 set -u -o pipefail