ADDITIONAL SYSTEM INFORMATION :
Debian trixie/sid

Package: openjdk-21-jre-headless
Architecture: amd64
Version: 21.0.5+11-1

classworlds.conf=/usr/share/maven/bin/m2.conf
file.encoding=UTF-8
file.separator=/
guice.disable.misplaced.annotation.check=true
jansi.mode=force
java.class.path=/usr/share/maven/boot/plexus-classworlds-2.x.jar
java.class.version=65.0
java.home=/usr/lib/jvm/java-21-openjdk-amd64
java.io.tmpdir=/tmp
java.library.path=/usr/java/packages/lib:/usr/lib/x86_64-linux-gnu/jni:/lib/x86_64-linux-gnu:/usr/lib/x86_64-linux-gnu:/usr/lib/jni:/lib:/usr/lib
java.runtime.name=OpenJDK Runtime Environment
java.runtime.version=21.0.5+11-Debian-1
java.specification.name=Java Platform API Specification
java.specification.vendor=Oracle Corporation
java.specification.version=21
java.vendor.url.bug=https://bugs.debian.org/openjdk-21
java.vendor.url=https://tracker.debian.org/openjdk-21
java.vendor=Debian
java.version.date=2024-10-15
java.version=21.0.5
java.vm.compressedOopsMode=Zero based
java.vm.info=mixed mode, sharing
java.vm.name=OpenJDK 64-Bit Server VM
java.vm.specification.name=Java Virtual Machine Specification
java.vm.specification.vendor=Oracle Corporation
java.vm.specification.version=21
java.vm.vendor=Debian
java.vm.version=21.0.5+11-Debian-1
jdk.debug=release
library.jansi.path=/usr/share/maven/lib/jansi-native
line.separator=
maven.conf=/usr/share/maven/conf
maven.home=/usr/share/maven
maven.multiModuleProjectDirectory=/...../kryo
native.encoding=UTF-8
os.arch=amd64
os.name=Linux
os.version=6.11.2-amd64
path.separator=:
stderr.encoding=UTF-8
stdout.encoding=UTF-8
sun.arch.data.model=64
sun.boot.library.path=/usr/lib/jvm/java-21-openjdk-amd64/lib
sun.cpu.endian=little
sun.io.unicode.encoding=UnicodeLittle
sun.java.command=org.codehaus.plexus.classworlds.launcher.Launcher help:system
sun.java.launcher=SUN_STANDARD
sun.jnu.encoding=UTF-8
sun.management.compiler=HotSpot 64-Bit Tiered Compilers
user.country=US
user.dir=/...../kryo
user.home=/.....
user.language=en
user.name=user
user.timezone=Etc/UTC


A DESCRIPTION OF THE PROBLEM :
While investigating reprotest failures on the -java-doc package of a
proposed package update I discovered that:
- libmaven-javadoc-plugin-java generates a package list (@packages argument to
javadoc) with an ordering that varies depending on filesystem ordering; as that
file is not included in the resulting package that alone would not be an issue
- javadoc output may vary depending on the ordering of the package list.

These variations are less frequent with the JDK 21 than they used to be with
older JDKs but will still happen in about 1/10 of the permutations, see Reproducing the Issue.

Example of a difference in generated content:
--- ttt/04/index-all.html 2024-12-04 09:23:51.542350370 +0000
+++ ttt/01/index-all.html 2024-12-04 09:23:31.906425220 +0000
@@ -176,7 +176,7 @@
 </dd>
 <dt><a href="com/esotericsoftware/kryo/io/ByteBufferInput.html#%3Cinit%3E()"
class="member-name-link">ByteBufferInput()</a> - Constructor for class
com.esotericsoftware.kryo.io.<a
href="com/esotericsoftware/kryo/io/ByteBufferInput.html" title="class in
com.esotericsoftware.kryo.io">ByteBufferInput</a></dt>
 <dd>
-<div class="block">Creates an uninitialized Input, <a
href="com/esotericsoftware/kryo/io/ByteBufferInput.html#setBuffer(java.nio.ByteBuffer)"><code>setBuffer(ByteBuffer)</code></a>
must be called before the Input is used.</div>
+<div class="block">Creates an uninitialized Input, <a
href="com/esotericsoftware/kryo/io/ByteBufferInput.html#setBuffer(java.nio.ByteBuffer)"><code>ByteBufferInput.setBuffer(ByteBuffer)</code></a>
must be called before the Input is used.</div>
 </dd>
 <dt><a
href="com/esotericsoftware/kryo/io/ByteBufferInput.html#%3Cinit%3E(byte%5B%5D)"
class="member-name-link">ByteBufferInput(byte[])</a> - Constructor for class
com.esotericsoftware.kryo.io.<a
href="com/esotericsoftware/kryo/io/ByteBufferInput.html" title="class in
com.esotericsoftware.kryo.io">ByteBufferInput</a></dt>
 <dd>

This issue can be reproduced by just shuffling the packages list before invoking javadoc.

I believe that this issue deserves a fix in javadoc as its output is not expected to change with the ordering of the packages list.

Related Debian issue: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1089013




STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
git clone --depth 1 -b kryo-parent-5.6.2 https://github.com/EsotericSoftware/kryo.git
cd kryo
mvn -Ddebug=true -Dnotimestamp=true javadoc:aggregate
echo ABCDEFGHIJKL > random-source \
    && shuf --random-source=random-source -o target/reports/apidocs/packages-shuffled target/reports/apidocs/packages \
    && javadoc -J-Duser.language= -J-Duser.country= @target/reports/apidocs/options @target/reports/apidocs/packages-shuffled \
    && md5sum target/reports/apidocs/index-all.html
echo X1hO+cTJklfx > random-source \
    && shuf --random-source=random-source -o target/reports/apidocs/packages-shuffled target/reports/apidocs/packages \
    && javadoc -J-Duser.language= -J-Duser.country= @target/reports/apidocs/options @target/reports/apidocs/packages-shuffled \
    && md5sum target/reports/apidocs/index-all.html


EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
Generated files (and thus checksums) are identical with all permutations of the set of packages

ACTUAL -
# echo ABCDEFGHIJKL > random-source && ...
bb26bbd5fa3ed9734cb7bfc8e9654a7e target/reports/apidocs/index-all.html
# note: contents of target/repors/apidocs/packages-shuffled
com.esotericsoftware.kryo.benchmarks.data
com.esotericsoftware.kryo.benchmarks.io
com.esotericsoftware.kryo.unsafe
com.esotericsoftware.kryo.io
com.esotericsoftware.kryo
com.esotericsoftware.kryo.util
com.esotericsoftware.kryo.serializers
com.esotericsoftware.kryo.benchmarks
com.esotericsoftware.kryo.benchmarks.jmh_generated
com.esotericsoftware.kryo.benchmarks.io.jmh_generated
# -----


# echo X1hO+cTJklfx > random-source && ...
12af108d877efbbe7aa7fc3e20ddf35a target/reports/apidocs/index-all.html
# note: contents of target/repors/apidocs/packages-shuffled
com.esotericsoftware.kryo.benchmarks.io.jmh_generated
com.esotericsoftware.kryo.benchmarks.jmh_generated
com.esotericsoftware.kryo.serializers
com.esotericsoftware.kryo.util
com.esotericsoftware.kryo.unsafe
com.esotericsoftware.kryo.io
com.esotericsoftware.kryo.benchmarks
com.esotericsoftware.kryo.benchmarks.data
com.esotericsoftware.kryo.benchmarks.io
com.esotericsoftware.kryo
# -----


CUSTOMER SUBMITTED WORKAROUND :
Have the maven-javadoc-plugin generate a sorted list of packages.
See: https://lists.apache.org/thread/h4m2lfrvdj9tj92rjckclx8sxvbx6jth

FREQUENCY : often