Finish enabling cache-cleanup by default

- Add deprecation warning for `gradle-home-cache-cleanup`
- Change default for `dependency-submission` to `cache-cleanup: on-success`
- Update documentation for changed default

dependency-submission/action.yml

@@ -63,12 +63,11 @@ inputs:
       By default, no cleanup is performed. It can be configured to run every time, or only when all Gradle builds succeed for the Job. 
       Valid values are 'never', 'on-success' and 'always'.
     required: false
-    default: 'never'
+    default: 'on-success'
 
   gradle-home-cache-cleanup:
     description: When 'true', the action will attempt to remove any stale/unused entries from the Gradle User Home prior to saving to the GitHub Actions cache.
     required: false
-    default: false
     deprecation-message: This input has been superceded by the 'cache-cleanup' input parameter.
 
   gradle-home-cache-includes:

docs/deprecation-upgrade-guide.md

@@ -148,3 +148,15 @@ These deprecated build-scan parameters are scheduled to be removed in `setup-gra
 Gradle Enterprise has been renamed to Develocity starting from Gradle plugin 3.17 and Develocity server 2024.1.
 In v4 release of the action, it will require setting the access key with the `develocity-access-key` input and Develocity 2024.1 at least to generate short-lived tokens.
 If those requirements are not met, the `GRADLE_ENTERPRISE_ACCESS_KEY` env var will be cleared out and build scan publication or other authenticated Develocity operations won't be possible.
+
+## The `gradle-home-cache-cleanup` input parameter has been replaced by `cache-cleanup`
+
+In versions of the action prior to `v4`, the boolean `gradle-home-cache-cleanup` parameter allows users to opt-in 
+to cache cleanup, removing unused files in Gradle User Home prior to saving to the cache.
+
+With `v4`, cache-cleanup is enabled by default, and controlled by the `cache-cleanup` input parameter.
+
+To remove this deprecation:
+- If you are using `gradle-home-cache-cleanup: true` in your workflow, you can remove this option as this is now enabled by default.
+- If you want cache-cleanup to run even when a Gradle build fails, then add the `cache-cleanup: always` input.
+- If cache-cleanup is causing problems with your workflow, you can disable it with `cache-cleanup: never`.

docs/setup-gradle.md

@@ -153,22 +153,29 @@ In certain circumstances it may be desirable to start with a clean Gradle User H
 cache-write-only: true
 ```
 
-### Enabling cache cleanup
+### Configuring cache cleanup
 
-The Gradle User Home directory tends to grow over time. When you switch to a new Gradle wrapper version or upgrade a dependency version
+The Gradle User Home directory tends to grow over time. When you switch to a new Gradle wrapper version 
-the old files are not automatically and immediately removed. While this can make sense in a local environment, in a GitHub Actions environment
+or upgrade a dependency version the old files are not automatically and immediately removed. 
+While this can make sense in a local environment, in a GitHub Actions environment
+While this can make sense in a local environment, in a GitHub Actions environment
 it can lead to ever-larger Gradle User Home cache entries being saved and restored.
 
-To avoid this situation, The `setup-gradle` action supports the `cache-cleanup` parameter.
+To avoid this situation, the `setup-gradle` and `dependency-submission` actions will perform "cache-cleanup", 
-When cache-cleanup is enabled, this feature will attempt to delete any files in the Gradle User Home that were not used by Gradle during the GitHub Actions Workflow, before saving the Gradle User Home to the GitHub Actions cache.
+purging any unused files from the Gradle User Home before saving it to the GitHub Actions cache. 
+Cache cleanup will attempt to remove any files that are initially restored to the Gradle User Home directory 
+but that are not used used by Gradle during the GitHub Actions Workflow.
 
-If cache cleanup runs after a failing Gradle build, it is possible that some required files and dependencies will not be touched, and will be removed.
+If a Gradle build fails when running the Job, then it is possible that some required files and dependencies 
-To prevent this scenario, cache cleanup can be configured to run only when all Gradle builds in the Job are successful.
+will not be touched during the Job. To prevent these files from being purged, the default behavior is for 
+cache cleanup to run only when all Gradle builds in the Job are successful.
 
-Gradle Home cache cleanup is considered experimental and is disabled by default.  You can enable this feature for the action as follows:
+Gradle Home cache cleanup is enabled by default, and can be controlled by the `cache-cleanup` parameter as follows:
-```yaml
+- `cache-cleanup: always`: Always run cache cleanup, even when a Gradle build fails in the Job.
-cache-cleanup: 'on-success' # Valid values are 'never' (default), 'on-success' and 'always'
+- `cache-cleanup: on-success` (default): Run cache cleanup when the Job contains no failing Gradle builds.
-```
+- `cache-cleanup: never`: Disable cache cleanup for the Job.
+
+Cache cleanup will never run when the cache is configured as read-only or disabled.
 
 ### Overwriting an existing Gradle User Home
 
@@ -373,14 +380,6 @@ gradle-home-cache-excludes: |
 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.
 
-### Remove unused files from Gradle User Home before saving to the cache
-
-The Gradle User Home directory tends to grow over time. When you switch to a new Gradle wrapper version or upgrade a dependency version
-the old files are not automatically and immediately removed. While this can make sense in a local environment, in a GitHub Actions environment
-it can lead to ever-larger Gradle User Home cache entries being saved and restored.
-
-See [Enabling cache cleanup](#enabling-cache-cleanup) for a mechanism to mitigate this problem.
-
 ### Disable local build-cache when remote build-cache is available
 
 If you have a remote build-cache available for your build, then it is recommended to do the following:

setup-gradle/action.yml

@@ -51,7 +51,6 @@ inputs:
   gradle-home-cache-cleanup:
     description: When 'true', the action will attempt to remove any stale/unused entries from the Gradle User Home prior to saving to the GitHub Actions cache.
     required: false
-    default: false
     deprecation-message: This input has been superceded by the 'cache-cleanup' input parameter.
 
   gradle-home-cache-includes:

sources/src/caching/cache-reporting.ts

@@ -1,26 +1,26 @@
 import * as cache from '@actions/cache'
 
-export const DEFAULT_CACHE_ENABLED_REASON = `[Cache was enabled](https://github.com/gradle/actions/blob/v3/docs/setup-gradle.md#caching-build-state-between-jobs). Action attempted to both restore and save the Gradle User Home.`
+export const DEFAULT_CACHE_ENABLED_REASON = `[Cache was enabled](https://github.com/gradle/actions/blob/main/docs/setup-gradle.md#caching-build-state-between-jobs). Action attempted to both restore and save the Gradle User Home.`
 
-export const DEFAULT_READONLY_REASON = `[Cache was read-only](https://github.com/gradle/actions/blob/v3/docs/setup-gradle.md#using-the-cache-read-only). By default, the action will only write to the cache for Jobs running on the default branch.`
+export const DEFAULT_READONLY_REASON = `[Cache was read-only](https://github.com/gradle/actions/blob/main/docs/setup-gradle.md#using-the-cache-read-only). By default, the action will only write to the cache for Jobs running on the default branch.`
 
-export const DEFAULT_DISABLED_REASON = `[Cache was disabled](https://github.com/gradle/actions/blob/v3/docs/setup-gradle.md#disabling-caching) via action confiugration. Gradle User Home was not restored from or saved to the cache.`
+export const DEFAULT_DISABLED_REASON = `[Cache was disabled](https://github.com/gradle/actions/blob/main/docs/setup-gradle.md#disabling-caching) via action confiugration. Gradle User Home was not restored from or saved to the cache.`
 
-export const DEFAULT_WRITEONLY_REASON = `[Cache was set to write-only](https://github.com/gradle/actions/blob/v3/docs/setup-gradle.md#using-the-cache-write-only) via action configuration. Gradle User Home was not restored from cache.`
+export const DEFAULT_WRITEONLY_REASON = `[Cache was set to write-only](https://github.com/gradle/actions/blob/main/docs/setup-gradle.md#using-the-cache-write-only) via action configuration. Gradle User Home was not restored from cache.`
 
-export const EXISTING_GRADLE_HOME = `[Cache was disabled to avoid overwriting a pre-existing Gradle User Home](https://github.com/gradle/actions/blob/v3/docs/setup-gradle.md#overwriting-an-existing-gradle-user-home). Gradle User Home was not restored from or saved to the cache.`
+export const EXISTING_GRADLE_HOME = `[Cache was disabled to avoid overwriting a pre-existing Gradle User Home](https://github.com/gradle/actions/blob/main/docs/setup-gradle.md#overwriting-an-existing-gradle-user-home). Gradle User Home was not restored from or saved to the cache.`
 
-export const CLEANUP_DISABLED_READONLY = `[Cache cleanup](https://github.com/gradle/actions/blob/v3/docs/setup-gradle.md#enabling-cache-cleanup) is always disabled when cache is read-only or disabled.`
+export const CLEANUP_DISABLED_READONLY = `[Cache cleanup](https://github.com/gradle/actions/blob/main/docs/setup-gradle.md#configuring-cache-cleanup) is always disabled when cache is read-only or disabled.`
 
-export const DEFAULT_CLEANUP_ENABLED_REASON = `[Cache cleanup](https://github.com/gradle/actions/blob/v3/docs/setup-gradle.md#enabling-cache-cleanup) was enabled. Stale files in Gradle User Home were purged before saving to the cache.`
+export const DEFAULT_CLEANUP_ENABLED_REASON = `[Cache cleanup](https://github.com/gradle/actions/blob/main/docs/setup-gradle.md#configuring-cache-cleanup) was enabled. Stale files in Gradle User Home were purged before saving to the cache.`
 
-export const DEFAULT_CLEANUP_DISABLED_REASON = `[Cache cleanup](https://github.com/gradle/actions/blob/v3/docs/setup-gradle.md#enabling-cache-cleanup) was disabled via action parameter. No cleanup of Gradle User Home was performed.`
+export const DEFAULT_CLEANUP_DISABLED_REASON = `[Cache cleanup](https://github.com/gradle/actions/blob/main/docs/setup-gradle.md#configuring-cache-cleanup) was disabled via action parameter. No cleanup of Gradle User Home was performed.`
 
 export const CLEANUP_DISABLED_DUE_TO_FAILURE =
-    '[Cache cleanup was disabled due to build failure](https://github.com/gradle/actions/blob/v3/docs/setup-gradle.md#enabling-cache-cleanup). Use `cache-cleanup: always` to override this behavior.'
+    '[Cache cleanup was disabled due to build failure](https://github.com/gradle/actions/blob/main/docs/setup-gradle.md#configuring-cache-cleanup). Use `cache-cleanup: always` to override this behavior.'
 
 export const CLEANUP_DISABLED_DUE_TO_CONFIG_CACHE_HIT =
-    '[Cache cleanup was disabled due to configuration-cache reuse](https://github.com/gradle/actions/blob/v3/docs/setup-gradle.md#enabling-cache-cleanup). This is expected.'
+    '[Cache cleanup was disabled due to configuration-cache reuse](https://github.com/gradle/actions/blob/main/docs/setup-gradle.md#configuring-cache-cleanup). This is expected.'
 
 /**
  * Collects information on what entries were saved and restored during the action.

sources/src/configuration.ts

@@ -143,6 +143,14 @@ export class CacheConfig {
     }
 
     private getCacheCleanupOption(): CacheCleanupOption {
+        const legacyVal = getOptionalBooleanInput('gradle-home-cache-cleanup')
+        if (legacyVal !== undefined) {
+            deprecator.recordDeprecation(
+                'The `gradle-home-cache-cleanup` input parameter has been replaced by `cache-cleanup`'
+            )
+            return legacyVal ? CacheCleanupOption.Always : CacheCleanupOption.Never
+        }
+
         const val = core.getInput('cache-cleanup')
         switch (val.toLowerCase().trim()) {
             case 'always':
@@ -150,10 +158,7 @@ export class CacheConfig {
             case 'on-success':
                 return CacheCleanupOption.OnSuccess
             case 'never':
-                // When set to 'never' (the default), honour the legacy parameter setting.
+                return CacheCleanupOption.Never
-                return getBooleanInput('gradle-home-cache-cleanup')
-                    ? CacheCleanupOption.Always
-                    : CacheCleanupOption.Never
         }
         throw TypeError(
             `The value '${val}' is not valid for cache-cleanup. Valid values are: [never, always, on-success].`