Emit warnings when using deprecated inputs / actions (#139)

Fixes #108

docs/deprecation-upgrade-guide.md

@@ -0,0 +1,105 @@
+# Deprecation upgrade guide
+
+As these actions evolve, certain inputs, behaviour and usages are deprecated for removal. 
+Deprecated functionality will be fully supported during the current major release, and will be
+removed in the next major release. 
+Users will receive a deprecation warning when they rely on deprecated functionality, 
+prompting them to update their workflows.
+
+## Deprecated in v3.x
+
+### The action `gradle/gradle-build-action` has been replaced by `gradle/actions/setup-gradle`
+
+The `gradle-build-action` action has evolved, so that the core functionality is now to configure the
+Gradle environment for GitHub Actions. For clarity and consistency with other action (eg `setup-java`, `setup-node`), the `gradle-build-action` has been replaced by the `setup-gradle` action.
+
+As of `v3.x`, the `setup-gradle` and `gradle-build-action` actions are functionally identical,
+and are released with the same versions.
+
+To convert your workflows, simply replace:
+```
+   uses: gradle/gradle-build-action@v3
+```
+with
+```
+    uses: gradle/actions/setup-gradle@v3
+```
+
+### Using the action to execute Gradle via the `arguments` parameter is deprecated
+
+The core functionality of the `setup-gradle` (and `gradle-build-action`) actions is to configure your
+Gradle environment for GitHub Actions. Once the action has run, any subsequent Gradle executions will
+benefit from caching, reporting and other features of the action.
+
+Using the `arguments` parameter to execute Gradle directly is not necessary to benefit from this action.
+This input is deprecated, and will be removed in the `v4` major release of the action.
+
+To convert your workflows, replace any steps using the `arguments` parameter with 2 steps: one to `setup-gradle` and another that runs your Gradle build.
+
+For example, if your workflow looks like this:
+
+```
+steps:
+- name: Assemble the project
+  uses: gradle/actions/setup-gradle@v3
+  with:
+    arguments: 'assemble'
+
+ - name: Run the tests
+   uses: gradle/actions/setup-gradle@v3
+   with:
+     arguments: 'test'
+
+ - name: Run build in a subdirectory
+   uses: gradle/actions/setup-gradle@v3
+   with:
+     build-root-directory: another-build
+     arguments: 'build'
+```
+
+Then replace this with a single call to `setup-gradle` together with separate `run` steps to execute your build.
+
+```
+- name: Setup Gradle
+  uses: gradle/actions/setup-gradle@v3
+
+- name: Assemble the project
+  run: ./gradlew assemble
+
+- name: Run the tests
+  run: ./gradlew test
+
+- name: Run build in a subdirectory
+  working-directory: another-build
+  run: ./gradlew build
+```
+
+Using the action in this way gives you more control over how Gradle is executed, while still giving you
+all of the benefits of the `setup-gradle` action.
+
+The `arguments` parameter is scheduled to be removed in `setup-gradle@v4`.
+
+Note: if you are using the `gradle-build-action`, [see here](#the-action-gradlegradle-build-action-has-been-replaced-by-gradleactionssetup-gradle) for more details on how to migrate.
+
+### The `build-scan-terms-of-service` input parameters have been renamed
+
+With recent releases of the `com.gradle.develocity` plugin, key input parameters have been renamed.
+- `build-scan-terms-of-service-url` is now `build-scan-terms-of-use-url`
+- `build-scan-terms-of-service-agree` is now `build-scan-terms-of-use-agree`
+
+The standard URL for the terms of use has also changed to https://gradle.com/help/legal-terms-of-use
+
+To convert your workflows, change:
+```
+    build-scan-publish: true
+    build-scan-terms-of-service-url: "https://gradle.com/terms-of-service"
+    build-scan-terms-of-service-agree: "yes"
+```
+
+to this:
+```
+    build-scan-publish: true
+    build-scan-terms-of-use-url: "https://gradle.com/help/legal-terms-of-use"
+    build-scan-terms-of-use-agree: "yes"
+```
+These deprecated build-scan parameters are scheduled to be removed in `setup-gradle@v4` and `dependency-submission@v4`.

sources/src/build-scan.ts

@@ -1,5 +1,5 @@
 import * as core from '@actions/core'
-import {BuildScanConfig} from './input-params'
+import {BuildScanConfig} from './configuration'
 
 export function setup(config: BuildScanConfig): void {
     maybeExportVariable('DEVELOCITY_INJECTION_INIT_SCRIPT_NAME', 'gradle-actions.inject-develocity.init.gradle')

sources/src/caching/cache-key.ts

@@ -1,6 +1,6 @@
 import * as github from '@actions/github'
 
-import {CacheConfig, getJobMatrix} from '../input-params'
+import {CacheConfig, getJobMatrix} from '../configuration'
 import {hashStrings} from './cache-utils'
 
 const CACHE_PROTOCOL_VERSION = 'v1'

sources/src/caching/caches.ts

@@ -3,7 +3,7 @@ import {CacheListener} from './cache-reporting'
 import {GradleUserHomeCache} from './gradle-user-home-cache'
 import {CacheCleaner} from './cache-cleaner'
 import {DaemonController} from '../daemon-controller'
-import {CacheConfig} from '../input-params'
+import {CacheConfig} from '../configuration'
 
 const CACHE_RESTORED_VAR = 'GRADLE_BUILD_ACTION_CACHE_RESTORED'
 

sources/src/caching/gradle-home-extry-extractor.ts

@@ -9,7 +9,7 @@ import {CacheEntryListener, CacheListener} from './cache-reporting'
 import {cacheDebug, hashFileNames, isCacheDebuggingEnabled, restoreCache, saveCache, tryDelete} from './cache-utils'
 
 import {BuildResult, loadBuildResults} from '../build-results'
-import {CacheConfig} from '../input-params'
+import {CacheConfig} from '../configuration'
 import {getCacheKeyBase} from './cache-key'
 
 const SKIP_RESTORE_VAR = 'GRADLE_BUILD_ACTION_SKIP_RESTORE'

sources/src/caching/gradle-user-home-cache.ts

@@ -8,7 +8,7 @@ import {generateCacheKey} from './cache-key'
 import {CacheListener} from './cache-reporting'
 import {saveCache, restoreCache, cacheDebug, isCacheDebuggingEnabled, tryDelete} from './cache-utils'
 import {GradleHomeEntryExtractor, ConfigurationCacheEntryExtractor} from './gradle-home-extry-extractor'
-import {CacheConfig} from '../input-params'
+import {CacheConfig} from '../configuration'
 
 const RESTORED_CACHE_KEY_KEY = 'restored-cache-key'
 

sources/src/input-params.ts → sources/src/configuration.ts

@@ -1,11 +1,14 @@
 import * as core from '@actions/core'
 import * as github from '@actions/github'
 import * as cache from '@actions/cache'
+import * as deprecator from './deprecation-collector'
 import {SUMMARY_ENV_VAR} from '@actions/core/lib/summary'
 
 import {parseArgsStringToArgv} from 'string-argv'
 import path from 'path'
 
+const ACTION_ID_VAR = 'GRADLE_ACTION_ID'
+
 export class DependencyGraphConfig {
     getDependencyGraphOption(): DependencyGraphOption {
         const val = core.getInput('dependency-graph')
@@ -215,6 +218,11 @@ export class BuildScanConfig {
         if (newProp !== '') {
             return newProp
         }
+        const oldProp = core.getInput(oldPropName)
+        if (oldProp !== '') {
+            deprecator.recordDeprecation('The `build-scan-terms-of-service` input parameters have been renamed')
+            return oldProp
+        }
         return core.getInput(oldPropName)
     }
 }
@@ -236,6 +244,11 @@ export class GradleExecutionConfig {
 
     getArguments(): string[] {
         const input = core.getInput('arguments')
+        if (input.length !== 0) {
+            deprecator.recordDeprecation(
+                'Using the action to execute Gradle via the `arguments` parameter is deprecated'
+            )
+        }
         return parseArgsStringToArgv(input)
     }
 
@@ -261,6 +274,14 @@ export function getWorkspaceDirectory(): string {
     return process.env[`GITHUB_WORKSPACE`] || ''
 }
 
+export function getActionId(): string | undefined {
+    return process.env[ACTION_ID_VAR]
+}
+
+export function setActionId(id: string): void {
+    core.exportVariable(ACTION_ID_VAR, id)
+}
+
 export function parseNumericInput(paramName: string, paramValue: string, paramDefault: number): number {
     if (paramValue.length === 0) {
         return paramDefault

sources/src/dependency-graph.ts

@@ -10,7 +10,7 @@ import * as path from 'path'
 import fs from 'fs'
 
 import {PostActionJobFailure} from './errors'
-import {DependencyGraphConfig, DependencyGraphOption, getGithubToken, getWorkspaceDirectory} from './input-params'
+import {DependencyGraphConfig, DependencyGraphOption, getGithubToken, getWorkspaceDirectory} from './configuration'
 
 const DEPENDENCY_GRAPH_PREFIX = 'dependency-graph_'
 

sources/src/dependency-submission/main.ts

@@ -10,14 +10,18 @@ import {
     CacheConfig,
     DependencyGraphConfig,
     DependencyGraphOption,
-    GradleExecutionConfig
-} from '../input-params'
+    GradleExecutionConfig,
+    setActionId
+} from '../configuration'
+import {saveDeprecationState} from '../deprecation-collector'
 
 /**
  * The main entry point for the action, called by Github Actions for the step.
  */
 export async function run(): Promise<void> {
     try {
+        setActionId('gradle/actions/dependency-submission')
+
         // Configure Gradle environment (Gradle User Home)
         await setupGradle.setup(new CacheConfig(), new BuildScanConfig())
 
@@ -49,6 +53,8 @@ export async function run(): Promise<void> {
         )
 
         await dependencyGraph.complete(config)
+
+        saveDeprecationState()
     } catch (error) {
         core.setFailed(String(error))
         if (error instanceof Error && error.stack) {

sources/src/dependency-submission/post.ts

@@ -1,7 +1,7 @@
 import * as core from '@actions/core'
 import * as setupGradle from '../setup-gradle'
 
-import {CacheConfig, SummaryConfig} from '../input-params'
+import {CacheConfig, SummaryConfig} from '../configuration'
 import {PostActionJobFailure} from '../errors'
 
 // Catch and log any unhandled exceptions.  These exceptions can leak out of the uploadChunk method in

sources/src/deprecation-collector.ts

@@ -0,0 +1,54 @@
+import * as core from '@actions/core'
+import {getActionId} from './configuration'
+
+const DEPRECATION_UPGRADE_PAGE = 'https://github.com/gradle/actions/blob/main/docs/deprecation-upgrade-guide.md'
+const recordedDeprecations: Deprecation[] = []
+
+export class Deprecation {
+    constructor(readonly message: string) {}
+
+    getDocumentationLink(): string {
+        const deprecationAnchor = this.message
+            .toLowerCase()
+            .replace(/[^\w\s-]|_/g, '')
+            .replace(/ /g, '-')
+        return `${DEPRECATION_UPGRADE_PAGE}#${deprecationAnchor}`
+    }
+}
+
+export function recordDeprecation(message: string): void {
+    if (!recordedDeprecations.some(deprecation => deprecation.message === message)) {
+        recordedDeprecations.push(new Deprecation(message))
+    }
+}
+
+export function getDeprecations(): Deprecation[] {
+    return recordedDeprecations
+}
+
+export function emitDeprecationWarnings(): void {
+    if (recordedDeprecations.length > 0) {
+        core.warning(
+            `This job uses deprecated functionality from the '${getActionId()}' action. Consult the Job Summary for more details.`
+        )
+        for (const deprecation of recordedDeprecations) {
+            core.info(`DEPRECATION: ${deprecation.message}. See ${deprecation.getDocumentationLink()}`)
+        }
+    }
+}
+
+export function saveDeprecationState(): void {
+    core.saveState('deprecations', JSON.stringify(recordedDeprecations))
+}
+
+export function restoreDeprecationState(): void {
+    const stringRep = core.getState('deprecations')
+    if (stringRep === '') {
+        return
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    JSON.parse(stringRep).forEach((obj: any) => {
+        recordedDeprecations.push(new Deprecation(obj.message))
+    })
+}

sources/src/execution/provision.ts

@@ -8,7 +8,7 @@ import * as toolCache from '@actions/tool-cache'
 
 import * as gradlew from './gradlew'
 import {handleCacheFailure} from '../caching/cache-utils'
-import {CacheConfig} from '../input-params'
+import {CacheConfig} from '../configuration'
 
 const gradleVersionsBaseUrl = 'https://services.gradle.org/versions'
 

sources/src/job-summary.ts

@@ -3,7 +3,8 @@ import * as github from '@actions/github'
 import {RequestError} from '@octokit/request-error'
 
 import {BuildResult} from './build-results'
-import {SummaryConfig, getGithubToken} from './input-params'
+import {SummaryConfig, getActionId, getGithubToken} from './configuration'
+import {Deprecation, getDeprecations} from './deprecation-collector'
 
 export async function generateJobSummary(
     buildResults: BuildResult[],
@@ -78,8 +79,31 @@ Note that this permission is never available for a workflow triggered from a rep
 }
 
 function renderSummaryTable(results: BuildResult[]): string {
+    return `${renderDeprecations()}\n${renderBuildResults(results)}`
+}
+
+function renderDeprecations(): string {
+    const deprecations = getDeprecations()
+    if (deprecations.length === 0) {
+        return ''
+    }
+    return `
+<h4>Deprecation warnings</h4>
+This job uses deprecated functionality from the <code>${getActionId()}</code> action. Follow the links for upgrade details.
+<ul>
+    ${deprecations.map(deprecation => `<li>${getDeprecationHtml(deprecation)}</li>`).join('')}
+</ul>
+
+<h4>Gradle Build Results</h4>`
+}
+
+function getDeprecationHtml(deprecation: Deprecation): string {
+    return `<a href="${deprecation.getDocumentationLink()}" target="_blank">${deprecation.message}</a>`
+}
+
+function renderBuildResults(results: BuildResult[]): string {
     if (results.length === 0) {
-        return 'No Gradle build results detected.'
+        return '<b>No Gradle build results detected.</b>'
     }
 
     return `

sources/src/setup-gradle.ts

@@ -9,7 +9,7 @@ import * as buildScan from './build-scan'
 import {loadBuildResults, markBuildResultsProcessed} from './build-results'
 import {CacheListener, generateCachingReport} from './caching/cache-reporting'
 import {DaemonController} from './daemon-controller'
-import {BuildScanConfig, CacheConfig, SummaryConfig, getWorkspaceDirectory} from './input-params'
+import {BuildScanConfig, CacheConfig, SummaryConfig, getWorkspaceDirectory} from './configuration'
 
 const GRADLE_SETUP_VAR = 'GRADLE_BUILD_ACTION_SETUP_COMPLETED'
 const USER_HOME = 'USER_HOME'