Enhance docs about reproducible builds (#1882)

* Enhance docs about reproducible builds

* Apply suggestions from code review

* Update docs/configuration/reproducible-builds/README.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Zongle Wang <wangzongler@gmail.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

docs/configuration/reproducible-builds/README.md

@@ -3,23 +3,52 @@
 By default, JAR files generated by Gradle (with or without Shadow) for a single project with the same source code may
 not be identical to each other. Sometimes it's desirable to configure a project to consistently output a byte-for-byte
 identical JAR on every build. Gradle supports this with the following configuration, and Shadow will correctly respect
-these settings too:
+these settings too.
+
+Besides file timestamps and file order, this configuration also ensures that all files in the JAR are set to have the
+same permissions, irrespective of the locally configured umask.
+
+More information about reproducible builds can be found at [reproducible-builds.org](https://reproducible-builds.org/).
 
 === "Kotlin"
 
     ```kotlin
+    import java.nio.file.Files
+    import java.nio.file.attribute.PosixFilePermission
+
     tasks.withType<AbstractArchiveTask>().configureEach {
       isPreserveFileTimestamps = false
       isReproducibleFileOrder = true
+
+      eachFile {
+        permissions {
+          val isExec =
+            Files.getPosixFilePermissions(file.toPath()).contains(PosixFilePermission.OWNER_EXECUTE)
+          unix(if (isExec) "755" else "644")
+        }
+      }
+      dirPermissions { unix("755") }
     }
     ```
 
 === "Groovy"
 
     ```groovy
+    import java.nio.file.Files
+    import java.nio.file.attribute.PosixFilePermission
+
     tasks.withType(AbstractArchiveTask).configureEach {
       preserveFileTimestamps = false
       reproducibleFileOrder = true
+
+      eachFile {
+          permissions {
+              def isExec =
+                      Files.getPosixFilePermissions(file.toPath()).contains(PosixFilePermission.OWNER_EXECUTE)
+              unix(isExec ? '755' : '644')
+          }
+      }
+      dirPermissions { unix('755') }
     }
     ```