docs(owlbot-java): explaining why not using formatter in pom.xml (#1511)

Fixes #1502

docker/owlbot/java/Dockerfile

@@ -15,6 +15,10 @@
 # build from the root of this repo:
 FROM gcr.io/cloud-devrel-public-resources/java8
 
+# The OwlBot Java postprocessor does not rely on project's Java formatter.
+# When you upgrade the formatter version, see the issue below for the required
+# changes:
+# https://github.com/googleapis/synthtool/issues/1502
 ARG JAVA_FORMAT_VERSION=1.7
 
 RUN apt-get install -y --no-install-recommends jq

docker/owlbot/java/bin/format_source.sh

@@ -15,6 +15,11 @@
 
 set -e
 
+# Why OwlBot Java postprocessor does not use the formatter defined in pom.xml?
+# It's because the postprocessor runs in a privileged (albeit limited)
+# environment. We limit the risk of running somebody else's malicious Maven
+# plugin code in the environment.
+
 # Find all the java files relative to the current directory and format them
 # using google-java-format
 list="$(find . -name '*.java' -not -path ".*/samples/snippets/generated/**/*" )"
@@ -33,6 +38,7 @@ do
   fi
 done
 
+# This JAR file is downloaded by Dockerfile
 cat $tmpfile | xargs java -jar /owlbot/google-java-format.jar --replace
 
 rm $tmpfile