diff --git a/build-compare.changes b/build-compare.changes
index dddd201..97b96dc 100644
--- a/build-compare.changes
+++ b/build-compare.changes
@@ -1,3 +1,8 @@
+-------------------------------------------------------------------
+Thu Sep 24 06:47:22 UTC 2009 - aj@suse.de
+
+- Add comments.
+
 -------------------------------------------------------------------
 Wed Sep 23 15:17:49 UTC 2009 - aj@suse.de
 
diff --git a/build-compare.spec b/build-compare.spec
index bf3558a..2aab2df 100644
--- a/build-compare.spec
+++ b/build-compare.spec
@@ -24,7 +24,7 @@ Group:          Development/Tools/Building
 AutoReqProv:    on
 Summary:        Build Result Compare Script
 Version:        2009.08.20
-Release:        2
+Release:        3
 Source:         same-build-result.sh
 Source1:        rpm-check.sh
 Source2:        COPYING
diff --git a/same-build-result.sh b/same-build-result.sh
index ce2125d..aab2e5d 100644
--- a/same-build-result.sh
+++ b/same-build-result.sh
@@ -7,6 +7,8 @@
 #
 # The script decides if the new build differes from the former one,
 # using rpm-check.sh.
+# The script is called as part of the build process as:
+# /usr/lib/build/same-build-result.sh /.build.oldpackages /usr/src/packages/RPMS /usr/src/packages/SRPMS
 
 CMPSCRIPT=${0%/*}/rpm-check.sh
 
@@ -50,6 +52,10 @@ bash $CMPSCRIPT "$osrpm" "$nsrpm" || exit 1
 
 # technically we should not all exclude all -32bit but filter for different archs, but it would be better
 # if this script ran earlier in the build
+# sort the rpms so that both lists have the same order
+# problem: a package can contain both noarch and arch subpackages, so we have to 
+# take care of proper sorting of NEWRPMS, e.g. noarch/x.rpm and x86_64/w.rpm since OLDRPMS 
+# has all the packages in a single directory and would sort this as w.rpm, x.rpm.
 OLDRPMS=($(find "$OLDDIR" -name \*rpm -a ! -name \*src.rpm|sort|grep -v -- -32bit|grep -v -- -64bit|grep -v -- -x86))
 NEWRPMS=($(find $NEWDIRS -name \*rpm -a ! -name \*src.rpm|sort --field-separator=/ --key=7|grep -v -- -32bit|grep -v -- -64bit|grep -v -- -x86))