Improve docs linked for wrapper-validation failure

Author: bigdaz

docs/wrapper-validation.md

@@ -93,18 +93,22 @@ We recommend the message commit contents of:
 
 From there, you can easily follow the rest of the prompts to create a Pull Request against the project.
 
-## Reporting Failures
+## Validation Failures
 
-If this GitHub action fails because a `gradle-wrapper.jar` doesn't match one of our published SHA-256 checksums,
-we highly recommend that you reach out to us at [[email protected]](mailto:[email protected]).
+A wrapper jar can fail validation for a few reasons:
+1. The wrapper is from a snapshot build of Gradle (nightly or release nightly) and you have not set `allow-snapshots`
+   or `allow-snapshot-wrappers` to `true`.
+2. The wrapper jar is from a version of Gradle with an unverifiable wrapper jar (see below).
+3. The wrapper jar was not published by Gradle, and could be compromised.
 
-**Note:** `gradle-wrapper.jar` generated by Gradle 3.3 to 4.0 are not verifiable because those files were dynamically generated by Gradle in a non-reproducible way. It's not possible to verify the `gradle-wrapper.jar` for those versions are legitimate using a hash comparison. You should try to determine if the `gradle-wrapper.jar` was generated by one of these versions before running the build.
+If this GitHub action fails because a `gradle-wrapper.jar` was not published by Gradle,
+we highly recommend that you reach out to us at [[email protected]](mailto:[email protected]).
 
-If the Gradle version in `gradle-wrapper.properties` is out of this range, you may need to regenerate the `gradle-wrapper.jar` by running `./gradlew wrapper`. If you need to use a version of Gradle between 3.3 and 4.0, you can use a newer version of Gradle to generate the `gradle-wrapper.jar`.
+#### Unverifiable Wrapper Jars
+Wrapper Jars generated by Gradle versions `3.3` to `4.0` are not verifiable because those files were dynamically generated by Gradle in a non-reproducible way. It's not possible to verify the `gradle-wrapper.jar` for those versions are legitimate using a hash comparison. If you have a validation failure, you should try to determine if the `gradle-wrapper.jar` was generated by one of these versions before running the build.
 
-If you're curious and want to explore what the differences are between the `gradle-wrapper.jar` in your possession
-and one of our valid release, you can compare them using this online utility: [diffoscope](https://try.diffoscope.org/).
-Regardless of what you find, we still kindly request that you reach out to us and let us know.
+- If the Gradle version in `gradle-wrapper.properties` is outside of this range, you can regenerate the `gradle-wrapper.jar` by running `./gradlew wrapper`. This will generate a new, verifiable wrapper jar.
+- If you need to run your build with a version of Gradle between 3.3 and 4.0, you can use a newer version of Gradle to generate the `gradle-wrapper.jar`.
 
 ## Resources
 

sources/src/wrapper-validation/wrapper-validator.ts

@@ -33,7 +33,7 @@ export async function validateWrappers(
     } else {
         core.info(result.toDisplayString())
         throw new JobFailure(
-            `Gradle Wrapper Validation Failed!\n  See https://github.com/gradle/actions/blob/main/docs/wrapper-validation.md#reporting-failures\n${result.toDisplayString()}`
+            `Gradle Wrapper Validation Failed!\n  See https://github.com/gradle/actions/blob/main/docs/wrapper-validation.md#validation-failures\n${result.toDisplayString()}`
         )
     }