MSOURCES-120 document key configuration for Reproducible Builds

Author: hboutemy

src/main/java/org/apache/maven/plugins/source/AbstractSourceJarMojo.java

@@ -284,11 +284,16 @@ protected void packageSources( List<MavenProject> theProjects )
 
         if ( sourceDateEpoch != 0 )
         {
+            // configure for Reproducible Builds based on source date epoch value
             JarArchiver j = archiver.getArchiver();
+
+            // 1. force timestamp of zip entries (at zip storage level, that ignores timezone)
             Calendar cal = Calendar.getInstance();
             long zipTime =
                 1000L * sourceDateEpoch - ( cal.get( Calendar.ZONE_OFFSET ) + cal.get( Calendar.DST_OFFSET ) );
             j.setLastModifiedDate( new Date( zipTime ) );
+
+            // 2. sort filenames in each directory when scanning filesystem
             j.setFilenameComparator( new Comparator<String>()
             {
                 @Override
@@ -297,8 +302,10 @@ public int compare( String s1, String s2 )
                     return s1.compareTo( s2 );
                 }
             } );
-            j.setFileMode( Archiver.DEFAULT_FILE_MODE ); // notice: overrides execute bit on Unix
-                                                         // (that is already ignored on Windows)
+
+            // 3. ignore file/directory mode from filesystem, since they may vary based on local user umask
+            // notice: this overrides execute bit on Unix (that is already ignored on Windows)
+            j.setFileMode( Archiver.DEFAULT_FILE_MODE ); 
             j.setDirectoryMode( Archiver.DEFAULT_DIR_MODE );
         }