Merge pull request #101 from gradle/dd/rename-parameters

Rename and document parameters for clarity 

- cache-paths -> gradle-home-cache-includes
- cache-exclude-paths -> gradle-home-cache-excludes
- CACHE_DEBUG_ENABLED -> GRADLE_BUILD_ACTION_CACHE_DEBUG_ENABLED

.github/workflows/failure-cases.yml

@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
 
 env:
-  CACHE_KEY_PREFIX: ${{github.workflow}}#${{github.run_number}}-
+  GRADLE_BUILD_ACTION_CACHE_KEY_PREFIX: ${{github.workflow}}#${{github.run_number}}-
 
 jobs:
 

.github/workflows/integTest-action-inputs.yml

@@ -6,7 +6,7 @@ on:
   workflow_dispatch:
 
 env:
-  CACHE_KEY_PREFIX: ${{github.workflow}}#${{github.run_number}}-
+  GRADLE_BUILD_ACTION_CACHE_KEY_PREFIX: ${{github.workflow}}#${{github.run_number}}-
 
 jobs:
   action-inputs:

.github/workflows/integTest-caching-config.yml

@@ -6,8 +6,8 @@ on:
   workflow_dispatch:
 
 env:
-  CACHE_KEY_PREFIX: ${{github.workflow}}#${{github.run_number}}-
+  GRADLE_BUILD_ACTION_CACHE_KEY_PREFIX: ${{github.workflow}}#${{github.run_number}}-
-  CACHE_DEBUG_ENABLED: true
+  GRADLE_BUILD_ACTION_CACHE_DEBUG_ENABLED: true
 
 jobs:
   # Run initial Gradle builds to push initial cache entries
@@ -27,11 +27,11 @@ jobs:
         arguments: test
         # Add "wrapper" to main cache entry and remove 'wrapper-zips' bundle
         # Exclude build-cache from main cache entry
-        cache-paths: |
+        gradle-home-cache-includes: |
             ["caches", "notifications", "wrapper"]
-        cache-exclude-paths: |
+        gradle-home-cache-excludes: |
             ["caches/build-cache-1"]
-        cache-artifact-bundles: |
+        gradle-home-cache-artifact-bundles: |
             [
               ["generated-gradle-jars", "caches/*/generated-gradle-jars/*.jar"],
               ["dependency-jars", "caches/modules-*/files-*/**/*.jar"],
@@ -56,11 +56,11 @@ jobs:
         arguments: test --offline
         cache-read-only: true
         # Need the same configuration when restoring state from cache
-        cache-paths: |
+        gradle-home-cache-includes: |
             ["caches", "notifications", "wrapper"]
-        cache-exclude-paths: |
+        gradle-home-cache-excludes: |
             ["caches/build-cache-1"]
-        cache-artifact-bundles: |
+        gradle-home-cache-artifact-bundles: |
             [
               ["generated-gradle-jars", "caches/*/generated-gradle-jars/*.jar"],
               ["dependency-jars", "caches/modules-*/files-*/**/*.jar"],

.github/workflows/integTest-caching.yml

@@ -6,7 +6,7 @@ on:
   workflow_dispatch:
 
 env:
-  CACHE_KEY_PREFIX: ${{github.workflow}}#${{github.run_number}}-
+  GRADLE_BUILD_ACTION_CACHE_KEY_PREFIX: ${{github.workflow}}#${{github.run_number}}-
 
 jobs:
   # Run initial Gradle builds to push initial cache entries
@@ -98,6 +98,6 @@ jobs:
       with:
         build-root-directory: __tests__/samples/groovy-dsl
         arguments: test
-        cache-artifact-bundles: '[]'
         cache-read-only: true
+        gradle-home-cache-artifact-bundles: '[]'
 

.github/workflows/integTest-execution.yml

@@ -6,7 +6,7 @@ on:
   workflow_dispatch:
 
 env:
-  CACHE_KEY_PREFIX: ${{github.workflow}}#${{github.run_number}}-
+  GRADLE_BUILD_ACTION_CACHE_KEY_PREFIX: ${{github.workflow}}#${{github.run_number}}-
 
 jobs:   
   # Tests for executing with different Gradle versions. 

.github/workflows/integTest-gradle-user-home.yml

@@ -6,7 +6,7 @@ on:
   workflow_dispatch:
 
 env:
-  CACHE_KEY_PREFIX: ${{github.workflow}}#${{github.run_number}}-
+  GRADLE_BUILD_ACTION_CACHE_KEY_PREFIX: ${{github.workflow}}#${{github.run_number}}-
   GRADLE_USER_HOME: custom/gradle/home
 
 jobs:

.github/workflows/integTest-kotlin-dsl.yml

@@ -6,8 +6,8 @@ on:
   workflow_dispatch:
 
 env:
-  CACHE_KEY_PREFIX: ${{github.workflow}}#${{github.run_number}}-
+  GRADLE_BUILD_ACTION_CACHE_KEY_PREFIX: ${{github.workflow}}#${{github.run_number}}-
-  CACHE_DEBUG_ENABLED: true
+  GRADLE_BUILD_ACTION_CACHE_DEBUG_ENABLED: true
 
 jobs:
   # Use kotlin-dsl project to verify caching of generated jars and compiled scripts

README.md

@@ -159,12 +159,9 @@ Caching is enabled by default. You can disable caching for the action as follows
 cache-disabled: true
 ```
 
-At this time it is not possible to fine-tune the caching performed by this action. 
-If you have a legitimate use case for fine-grained caching or restricting which files are cached, please raise an issue.
-
 ### Cache keys
 
-For cached distributions, the cache key is unique to the downloaded distribution. This will not change over time.
+For cached distributions outside of Gradle User Home, the cache key is unique to the downloaded distribution. This will not change over time.
 
 The state of the Gradle User Home and configuration-cache are highly dependent on the Gradle execution, so the cache key is composed of the current commit hash and the GitHub actions job id.
 As such, the cache key is likely to change on each subsequent run of GitHub actions. 
@@ -183,16 +180,36 @@ For example, you may want to write cache entries for builds on your `main` branc
 You can enable read-only caching for any of the caches as follows:
 
 ```yaml
-cache-read-only: true
+# Only write to the cache for builds on the 'main' branch.
+# Builds on other branches will only read existing entries from the cache.
+cache-read-only: ${{ github.ref != 'refs/heads/main' }}
 ```
 
+### Gradle User Home cache tuning
+
+As well as any wrapper distributions, the action will attempt to save and restore the `caches` and `notifications` directories from Gradle User Home.
+
+The contents to be cached can be fine tuned by including and excluding certain paths with Gradle User Home.
+
+```yaml
+# Cache downloaded JDKs in addition to the default directories.
+gradle-home-cache-includes: |
+    ["caches", "notifications", "jdks"]
+# Exclude the local build-cache from the directories cached.
+gradle-home-cache-excludes: |
+    ["caches/build-cache-1"]
+```
+
+You can specify any number of fixed paths or patterns to include or exclude. 
+File pattern support is documented at https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#patterns-to-match-file-paths.
+
 ### Cache debugging
 
-It is possible to enable additional debug logging for cache operations. You do via the `CACHE_DEBUG_ENABLED` environment variable:
+It is possible to enable additional debug logging for cache operations. You do via the `GRADLE_BUILD_ACTION_CACHE_DEBUG_ENABLED` environment variable:
 
 ```yaml
 env:
-  CACHE_DEBUG_ENABLED: true
+  GRADLE_BUILD_ACTION_CACHE_DEBUG_ENABLED: true
 ```
 
 Note that this setting will also prevent certain cache operations from running in parallel, further assisting with debugging.

action.yml

@@ -26,11 +26,26 @@ inputs:
     default: false
 
   cache-read-only:
-    description: When 'true', existing entries will be read from the cache but no entries will be written
+    description: When 'true', existing entries will be read from the cache but no entries will be written.
     required: false
-    # TODO: It might be useful to default to read-only for PRs, or non-main branch.
     default: false 
+  # e.g. Use the following setting to only write cache entries from your 'main' branch
+  #     cache-read-only: ${{ github.ref != 'refs/heads/main' }}
 
+  gradle-home-cache-includes:
+    description: Paths within Gradle User Home to cache.
+    required: false
+    default: |
+        ["caches", "notifications"]
+
+  gradle-home-cache-excludes:
+    description: Paths within Gradle User Home to exclude from cache.
+    required: false
+    default: |
+        [] 
+  # e.g. Use the following setting to prevent the local build cache from being saved/restored
+  #      gradle-home-cache-excludes: |
+  #           ["caches/build-cache-1"]
 
   # EXPERIMENTAL & INTERNAL CONFIGURATION PROPERTIES
   # The following action properties allow fine-grained tweaking of the action caching behaviour.
@@ -40,21 +55,7 @@ inputs:
     description: Used to uniquely identify the current job invocation. Defaults to the matrix values for this job; this should not be overridden by users (INTERNAL).
     required: false
     default: ${{ toJSON(matrix) }}
-
+  gradle-home-cache-artifact-bundles:
-  cache-paths:
-    description: Paths in Gradle User Home to cache. (EXPERIMENTAL - may be changed/removed without notice)
-    required: false
-    default: |
-        ["caches", "notifications"]
-
-  cache-exclude-paths:
-    description: Paths in Gradle User Home to exclude from cache. (EXPERIMENTAL - may be changed/removed without notice)
-    required: false
-    # eg ["caches/build-cache-1"] will prevent the local build cache from being saved/restored. 
-    default: |
-        [] 
-
-  cache-artifact-bundles:
     description: Names and patterns of artifact bundles to cache separately. (EXPERIMENTAL - may be changed/removed without notice)
     required: false
     default: |

src/cache-gradle-user-home.ts

@@ -14,6 +14,10 @@ import {
 
 const META_FILE_DIR = '.gradle-build-action'
 
+const INCLUDE_PATHS_PARAMETER = 'gradle-home-cache-includes'
+const EXCLUDE_PATHS_PARAMETER = 'gradle-home-cache-excludes'
+const ARTIFACT_BUNDLES_PARAMETER = 'gradle-home-cache-artifact-bundles'
+
 export class GradleUserHomeCache extends AbstractCache {
     private gradleUserHome: string
 
@@ -81,7 +85,7 @@ export class GradleUserHomeCache extends AbstractCache {
 
     private removeExcludedPaths(): void {
         const rawPaths: string[] = JSON.parse(
-            core.getInput('cache-exclude-paths')
+            core.getInput(EXCLUDE_PATHS_PARAMETER)
         )
         const resolvedPaths = rawPaths.map(x =>
             path.resolve(this.gradleUserHome, x)
@@ -189,7 +193,9 @@ export class GradleUserHomeCache extends AbstractCache {
     }
 
     protected getCachePath(): string[] {
-        const rawPaths: string[] = JSON.parse(core.getInput('cache-paths'))
+        const rawPaths: string[] = JSON.parse(
+            core.getInput(INCLUDE_PATHS_PARAMETER)
+        )
         rawPaths.push(META_FILE_DIR)
         const resolvedPaths = rawPaths.map(x => this.resolveCachePath(x))
         this.debug(`Using cache paths: ${resolvedPaths}`)
@@ -205,7 +211,9 @@ export class GradleUserHomeCache extends AbstractCache {
     }
 
     private getArtifactBundles(): Map<string, string> {
-        const artifactBundleDefinition = core.getInput('cache-artifact-bundles')
+        const artifactBundleDefinition = core.getInput(
+            ARTIFACT_BUNDLES_PARAMETER
+        )
         this.debug(
             `Using artifact bundle definition: ${artifactBundleDefinition}`
         )

src/cache-utils.ts

@@ -5,21 +5,27 @@ import * as crypto from 'crypto'
 import * as path from 'path'
 import * as fs from 'fs'
 
+const CACHE_DISABLED_PARAMETER = 'cache-disabled'
+const CACHE_READONLY_PARAMETER = 'cache-read-only'
+const JOB_CONTEXT_PARAMETER = 'workflow-job-context'
+const CACHE_DEBUG_VAR = 'GRADLE_BUILD_ACTION_CACHE_DEBUG_ENABLED'
+const CACHE_PREFIX_VAR = 'GRADLE_BUILD_ACTION_CACHE_KEY_PREFIX'
+
 export function isCacheDisabled(): boolean {
-    return core.getBooleanInput('cache-disabled')
+    return core.getBooleanInput(CACHE_DISABLED_PARAMETER)
 }
 
 export function isCacheReadOnly(): boolean {
-    return core.getBooleanInput('cache-read-only')
+    return core.getBooleanInput(CACHE_READONLY_PARAMETER)
 }
 
 export function isCacheDebuggingEnabled(): boolean {
-    return process.env['CACHE_DEBUG_ENABLED'] ? true : false
+    return process.env[CACHE_DEBUG_VAR] ? true : false
 }
 
 export function getCacheKeyPrefix(): string {
     // Prefix can be used to force change all cache keys (defaults to cache protocol version)
-    return process.env['CACHE_KEY_PREFIX'] || 'v3-'
+    return process.env[CACHE_PREFIX_VAR] || 'v3-'
 }
 
 function generateCacheKey(cacheName: string): CacheKey {
@@ -47,7 +53,7 @@ function generateCacheKey(cacheName: string): CacheKey {
 
 function determineJobContext(): string {
     // By default, we hash the full `matrix` data for the run, to uniquely identify this job invocation
-    const workflowJobContext = core.getInput('workflow-job-context')
+    const workflowJobContext = core.getInput(JOB_CONTEXT_PARAMETER)
     return hashStrings([workflowJobContext])
 }