This is an automated email from the ASF dual-hosted git repository.

slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-site.git

commit 6312be926e12e4c8bb42149c6157f7800b8f8fa8
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Sat Oct 31 19:58:15 2026 +0000

    Move diagnosing reproducible builds into the reproducible builds guide
---
 content/filtered-resources/.htaccess               |  1 +
 .../guides/mini/guide-reproducible-builds.md       | 92 ++++++++++++++++++++++
 2 files changed, 93 insertions(+)

diff --git a/content/filtered-resources/.htaccess 
b/content/filtered-resources/.htaccess
index db49b5bc..e184e769 100644
--- a/content/filtered-resources/.htaccess
+++ b/content/filtered-resources/.htaccess
@@ -27,6 +27,7 @@ Redirect Permanent 
/plugins/maven-checkstyle-plugin/customize.html /plugins/mave
 Redirect Permanent /plugins/maven-checkstyle-plugin/howto.html 
/plugins/maven-checkstyle-plugin/usage.html
 Redirect Permanent /plugins/maven-checkstyle-plugin/tips.html 
/plugins/maven-checkstyle-plugin/examples/multi-module-config.html
 
+Redirect Permanent /plugins/maven-artifact-plugin/reproducible.html 
/guides/mini/guide-reproducible-builds.html#Reading_the_artifact.3Acompare_output
 Redirect Permanent /shared/maven-archiver/examples/classpath.html 
/guides/mini/guide-manifest.html#Setting_Up_the_Classpath
 Redirect Permanent /shared/maven-archiver/examples/manifest.html 
/guides/mini/guide-manifest.html#Default_Manifest
 Redirect Permanent /shared/maven-archiver/examples/manifestEntries.html 
/guides/mini/guide-manifest.html#Manifest_Entries
diff --git a/content/markdown/guides/mini/guide-reproducible-builds.md 
b/content/markdown/guides/mini/guide-reproducible-builds.md
index 2a4b3330..e400c761 100644
--- a/content/markdown/guides/mini/guide-reproducible-builds.md
+++ b/content/markdown/guides/mini/guide-reproducible-builds.md
@@ -81,6 +81,98 @@ If something is still not reproducible after initial setup 
and [automatic check
 2. Find the plugin that generated this output.
 3. Check if a reproducible version of the plugin is available. If not, please 
open an issue to help plugin maintainers improving Reproducible Builds support 
at every plugin level.
 
+### Reading the artifact:compare output
+
+If `artifact:compare` reports that the current build output is not the same as 
the reference, the log shows where to look. This example rebuilds Doxia 1.9.1 
against the release published on Central:
+
+```
+$ mvn -Papache-release clean verify -Dgpg.skip artifact:compare
+[INFO] Scanning for projects...
+...
+[INFO] --- maven-artifact-plugin:3.7.0:buildinfo (default-cli) @ 
doxia-module-markdown ---
+[INFO] Saved aggregate info on build to 
/tmp/doxia-1.9.1/doxia-modules/doxia-module-markdown/target/doxia-module-markdown-1.9.1.buildinfo
+[INFO] Checking against reference build from central...
+Downloading from central: 
https://repo.maven.apache.org/maven2/org/apache/maven/doxia/doxia-module-markdown/1.9.1/doxia-module-markdown-1.9.1.buildinfo
+[WARNING] Reference buildinfo file not found: it will be generated from 
downloaded reference artifacts
+[INFO] Reference build java.version: 1.8 (from MANIFEST.MF Build-Jdk-Spec)
+[INFO] Reference build java.version: 1.8 (from MANIFEST.MF Build-Jdk-Spec)
+[ERROR] Current build java.version: 1.7 (from MANIFEST.MF Build-Jdk-Spec)
+[INFO] Reference build os.name: Unix (from pom.properties newline)
+[INFO] Minimal buildinfo generated from downloaded artifacts: 
/tmp/doxia-1.9.1/target/reference/doxia-module-markdown-1.9.1.buildinfo
+[WARNING] size mismatch doxia-logging-api-1.9.1.jar: investigate with 
diffoscope target/reference/doxia-logging-api-1.9.1.jar 
doxia-logging-api/target/doxia-logging-api-1.9.1.jar
+...
+[WARNING] size mismatch doxia-module-markdown-1.9.1.jar: investigate with 
diffoscope target/reference/doxia-module-markdown-1.9.1.jar 
doxia-modules/doxia-module-markdown/target/doxia-module-markdown-1.9.1.jar
+[WARNING] Reproducible Build output summary: 39 files ok, 18 different
+[WARNING] see diff target/reference/doxia-module-markdown-1.9.1.buildinfo 
doxia-modules/doxia-module-markdown/target/doxia-module-markdown-1.9.1.buildinfo
+[WARNING] see also 
https://maven.apache.org/guides/mini/guide-reproducible-builds.html
+[INFO] Reproducible Build output comparison saved to 
/tmp/doxia-1.9.1/doxia-modules/doxia-module-markdown/target/doxia-module-markdown-1.9.1.buildcompare
+[INFO] Aggregate buildcompare copied to 
/tmp/doxia-1.9.1/target/doxia-1.9.1.buildcompare
+...
+```
+
+The log has several parts worth reading:
+
+- the summary: `[WARNING] Reproducible Build output summary: 39 files ok, 18 
different`
+- key information on reference build environment:  
+    `[INFO] Reference build java.version: 1.8 (from MANIFEST.MF 
Build-Jdk-Spec)`  
+    `[INFO] Reference build os.name: Unix (from pom.properties newline)`  
+    which are the key requirements (JDK major version and Operating System) 
for the build environment to reproduce the reference build
+- eventual mismatch with current build environment:  
+    `[ERROR] Current build java.version: 1.7 (from MANIFEST.MF Build-Jdk-Spec)`
+- on each artifact different from reference, a command is provided to 
investigate differences using [diffoscope tool](https://diffoscope.org/), a 
diff tool working inside archives (jar, zip, tar, ...):  
+    simply copy paste provided command like `diffoscope 
target/reference/doxia-logging-api-1.9.1.jar 
doxia-logging-api/target/doxia-logging-api-1.9.1.jar` and you'll see where 
differences are:
+
+    ```shell
+    $ diffoscope target/reference/doxia-logging-api-1.9.1.jar 
doxia-logging-api/target/doxia-logging-api-1.9.1.jar
+    --- target/reference/doxia-logging-api-1.9.1.jar
+    +++ doxia-logging-api/target/doxia-logging-api-1.9.1.jar
+    ├── zipinfo /dev/stdin
+    │ @@ -1,8 +1,8 @@
+    │ -Zip file size: 11516 bytes, number of entries: 19
+    │ +Zip file size: 11497 bytes, number of entries: 19
+    │  -rw-r--r--  2.0 unx      337 b- defN 20-Feb-13 21:11 
META-INF/MANIFEST.MF
+    │  drwxr-xr-x  2.0 unx        0 b- stor 20-Feb-13 21:11 META-INF/
+    │  drwxr-xr-x  2.0 unx        0 b- stor 20-Feb-13 21:11 org/
+    │  drwxr-xr-x  2.0 unx        0 b- stor 20-Feb-13 21:11 org/apache/
+    │  drwxr-xr-x  2.0 unx        0 b- stor 20-Feb-13 21:11 org/apache/maven/
+    │  drwxr-xr-x  2.0 unx        0 b- stor 20-Feb-13 21:11 
org/apache/maven/doxia/
+    │  drwxr-xr-x  2.0 unx        0 b- stor 20-Feb-13 21:11 
org/apache/maven/doxia/logging/
+    │ @@ -11,11 +11,11 @@
+    │  drwxr-xr-x  2.0 unx        0 b- stor 20-Feb-13 21:11 
META-INF/maven/org.apache.maven.doxia/doxia-logging-api/
+    │  -rw-r--r--  2.0 unx     1641 b- defN 20-Feb-13 21:11 
META-INF/DEPENDENCIES
+    │  -rw-r--r--  2.0 unx    11358 b- defN 20-Feb-13 21:11 META-INF/LICENSE
+    │  -rw-r--r--  2.0 unx      177 b- defN 20-Feb-13 21:11 META-INF/NOTICE
+    │  -rw-r--r--  2.0 unx      716 b- defN 20-Feb-13 21:11 
org/apache/maven/doxia/logging/Log.class
+    │  -rw-r--r--  2.0 unx      198 b- defN 20-Feb-13 21:11 
org/apache/maven/doxia/logging/LogEnabled.class
+    │  -rw-r--r--  2.0 unx     2840 b- defN 20-Feb-13 21:11 
org/apache/maven/doxia/logging/PlexusLoggerWrapper.class
+    │ --rw-r--r--  2.0 unx     4208 b- defN 20-Feb-13 21:11 
org/apache/maven/doxia/logging/SystemStreamLog.class
+    │ +-rw-r--r--  2.0 unx     4192 b- defN 20-Feb-13 21:11 
org/apache/maven/doxia/logging/SystemStreamLog.class
+    │  -rw-r--r--  2.0 unx     1539 b- defN 20-Feb-13 21:11 
META-INF/maven/org.apache.maven.doxia/doxia-logging-api/pom.xml
+    │  -rw-r--r--  2.0 unx       74 b- defN 20-Feb-13 21:11 
META-INF/maven/org.apache.maven.doxia/doxia-logging-api/pom.properties
+    │ -19 files, 23088 bytes uncompressed, 8842 bytes compressed:  61.7%
+    │ +19 files, 23072 bytes uncompressed, 8823 bytes compressed:  61.8%
+    ├── META-INF/MANIFEST.MF
+    │ @@ -1,10 +1,10 @@
+    │  Manifest-Version: 1.0
+    │ +Implementation-Vendor: The Apache Software Foundation
+    │  Implementation-Title: Doxia :: Logging API
+    │  Implementation-Version: 1.9.1
+    │ +Build-Jdk-Spec: 1.7
+    │  Specification-Vendor: The Apache Software Foundation
+    │ -Specification-Title: Doxia :: Logging API
+    │ -Build-Jdk-Spec: 1.8
+    │  Created-By: Maven Jar Plugin 3.2.0
+    │ +Specification-Title: Doxia :: Logging API
+    │  Specification-Version: 1.9
+    │ -Implementation-Vendor: The Apache Software Foundation
+    ├── org/apache/maven/doxia/logging/PlexusLoggerWrapper.class
+    ...
+    ```
+
+In this example, reference build was done with JDK 8 (see `│ -Build-Jdk-Spec: 
1.8`), but the current build was done with JDK 7 (see `│ +Build-Jdk-Spec: 
1.7`): this explains both difference in content of `META-INF/MANIFEST.MF` of 
every .jar file, but also of some bytecode in `.class` files.
+
+When general environment issues have been fixed, find for each remaining issue 
which Maven plugin generated the content, and check whether an update of that 
plugin generates reproducible output: the [required upgrades 
list](/plugins/maven-artifact-plugin/plugin-issues.html) is a starting point.
+
 ## More Details
 
 Reproducible Builds for Maven:

Reply via email to