#799: Update tool-vendor-plea.adoc

documentation/tool-vendor-plea.adoc

@@ -63,8 +63,13 @@ But please follow best-practices and common sense and publish them as a new rele
 === Proper file format
 
 On Linux and Mac binaries and scripts need executable permission to be run (`chmod a+x «binary»`).
-Since ZIP files are unable to store such metainformation you should be smart and not use ZIP as file format at least for all other platforms than Windows.
-As a best practice never use ZIP but instead something like `*.tar.gz`.
+Theoretically ZIP files can also store such metadata but since this was later added to ZIP format.
+Therefore, many ZIP libraries are not supporting this feature at all or if they do they do it very poor.
+We started with apache commons-compress that unfortunetaly is already https://issues.apache.org/jira/browse/COMPRESS-562[buggy on simple extract].
+Then we discovered that `java.util.zip` from JDK https://stackoverflow.com/questions/54654170/what-are-the-extra-bytes-in-the-zipentry-used-for[cannot give reliable access to metadata such as executable flags].
+Finally, we found https://bugs.openjdk.org/browse/JDK-8213082[JDK-8213082] that lead us to the solution but caused many pitfalls and headaches until we came up with a unpacking of ZIP files that reliably preserves file permissions.
+
+As a best practice never use ZIP but instead something like `*.tar.gz` since TAR was designed with POSIX permissions from the start and then things just work.
 
 Unfortunately many famous tools violate this principle and provide ZIP files for Linux and Mac.
 As a result users unzip the package and then get a warm welcome when running the tool: