Describe limitations

[michael-o]

This closes #15

[hboutemy]

definitely no: that sentence is not true said like that, goes a wrong route about what Reproducible Builds is and what a rebuild comparison success or failure means

if you really want to say something in that direction, we can eventually say that

Having artifact:compare fail on your build does not always mean that the build is not reproducible: it may be that the environment of the current build has too much differences with the environment from the reference build (for example not same JDK release, not same Maven version, not same timezone, ...). Updating the environment may be sufficient to get the same build output as the reference build; then have achieved to reproduce the reference build.

On the other side, having a successful rebuild locally does not explicitely define what the environment prerequisites are, nor how strictly they are described: someone with another environment may discover later that an environment parameter was involved in rebuild comparison success that was implicitely set (like timezone, or Maven release used).

And defining what is acceptable as an environment prerequisite for judging that the build is sufficiently "easily" reproducible is out of the scope for the plugin: is it acceptable to require a timezone, or a user language, or a Maven version? This is more best-practices to ease rebuilders' life.

For example: efforts have been put in maven-jar-plugin to not store precise Maven release (major.minor.patch) or JDK release (major.minor.release_patch or JDK vendor) in output file, because it has been judged that it was adding too much constraints on the rebuild environment definition, without much value (experience shows that output result is stable).
In general, other plugins have tried to avoid depending on the timezone or user language. But nothing is absolute: one may require for a precise environment setup.

All these explanations are my experience from rebuilding releases done by others and publishing results on Maven Central https://github.com/jvm-repo-rebuild/reproducible-central
They are true, but I fear they are complex to grasp...

[michael-o]

Right, I will try to rephrase tomorrow.