From ceebe88cb73ce252e68d7d379fa5c90e15831753 Mon Sep 17 00:00:00 2001
From: Janek Bogucki <janekdb@gmail.com>
Date: Wed, 23 Sep 2015 21:58:15 +0100
Subject: Script to compare the current scaladoc with the parent commit's doc

---
 tools/scaladoc-diff | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100755 tools/scaladoc-diff

(limited to 'tools')

diff --git a/tools/scaladoc-diff b/tools/scaladoc-diff
new file mode 100755
index 0000000000..64dc025ecd
--- /dev/null
+++ b/tools/scaladoc-diff
@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+#
+# Script to compare the scaladoc of the current commit with the scaladoc
+# of the parent commit. No arguments.
+#
+
+
+oldsha=$(git log -1 --format="%H" HEAD^)
+oldsha=${oldsha#g}
+oldsha=${oldsha:0:10}
+
+sha=`sh tools/get-scala-commit-sha`
+echo "parent commit sha: $oldsha. current commit sha: $sha"
+
+# create scaladoc for parent commit if not done already
+if [ ! -f "build/scaladoc-output-$oldsha.txt" ]
+then
+  echo "making scaladoc for parent commit ($oldsha)"
+  git checkout HEAD^
+  ant docs.lib -Dscaladoc.raw.output='yes' > build/scaladoc-output-$oldsha.txt
+  cp -r build/scaladoc/ build/scaladoc-${oldsha}
+  git checkout $sha
+fi
+
+# create scaladoc for current commit
+echo "making scaladoc for current commit ($sha)"
+ant docs.lib -Dscaladoc.raw.output='yes' > build/scaladoc-output-$sha.txt
+cp -r build/scaladoc/ build/scaladoc-${sha}
+echo "opendiff build/scaladoc-output-$oldsha.txt build/scaladoc-output-$sha.txt"
+opendiff build/scaladoc-output-$oldsha.txt build/scaladoc-output-$sha.txt
+
+echo "Comparing files..."
+
+difffile=build/scaladoc-diff-${sha}-$oldsha.txt
+sh tools/scaladoc-compare build/scaladoc-${sha}/ build/scaladoc-$oldsha/ &> $difffile
+open $difffile &
+
+# Adapted from tools/scaladoc-compare
+echo "Comparing versions with difftool: build/scaladoc-${sha}/ build/scaladoc-$oldsha/"
+NEW_PATH=build/scaladoc-${sha}/
+OLD_PATH=build/scaladoc-$oldsha/
+
+FILES=`find $NEW_PATH -name '*.html.raw'`
+if [ "$FILES" == "" ]
+then
+  echo "No .html.raw files found in $NEW_PATH!"
+  exit 1
+fi
+
+for NEW_FILE in $FILES
+do
+  OLD_FILE=${NEW_FILE/$NEW_PATH/$OLD_PATH}
+  if [ -f $OLD_FILE ]
+  then
+    DIFF=`diff -q -w $NEW_FILE $OLD_FILE 2>&1`
+    if [ "$DIFF" != "" ]
+    then
+      opendiff $OLD_FILE $NEW_FILE > /dev/null
+      echo "next [y\N]? "
+      read -n 1 -s input
+
+      if [ "$input" == "N" ]
+      then exit 0
+      fi
+    fi
+  else
+    echo -e "$NEW_FILE: No corresponding file (expecting $OLD_FILE)\n\n"
+  fi
+done
+
+echo "Done."
-- 
cgit v1.2.3


From 006c0a4a343749f9a6a591e5cdec925effe1103a Mon Sep 17 00:00:00 2001
From: Janek Bogucki <janekdb@gmail.com>
Date: Sat, 3 Oct 2015 21:23:35 +0100
Subject: Enhance scaladoc-diff tool for Ubuntu.

Tested on Ubuntu 14.04.3 LTS.

SUMMARY

   1. Use `set -e` to ensure ant failure bails script.
   2. Make best effort to display scaladoc build diff.
   3. Quiet output from git checkout.
   4. Prefer plumbing over porcelain when getting hashes.
   5. Use short hashes to enhance output readability.
   6. Use branch name when available.
   7. Ensure scaladoc copies are clean.
   8. Remove redundant use of scaladoc-compare.
   9. Improve message formatting.
  10. Use $(...) instead of backticks for more legible code.
  11. Pause after reporting missing old file.
  12. Report missing new files.

DETAILS

1. Use `set -e` to ensure an ant failure bails the script. Turn off before
diff because diff returns an error code when the compared files differ,
which is expected to be seen.

2. Make best effort to display scaladoc build diff preferring graphical
clients.

opendiff is a Mac OS X command that opens a graphical diff display, meld
is a graphical client for Ubuntu and other distros. On Ubuntu fallback to
gvimdiff which will display graphically if possible otherwise in the
console. Ultimately default to diff.

Command detection taken from,

  http://stackoverflow.com/questions/592620/check-if-a-program-exists-from-a-bash-script

3. Quiet output from git checkout to avoid detached head warning.

The user does not need to see the detached head warning when running this.

4. Prefer plumbing over porcelain to avoid 'not found' error when getting
SHA1s.

Calling get-scala-commit-sha errors out on Ubuntu 14.04.3 with
Bash 4.3.11 with these messages,

    tools/get-scala-commit-sha: 11: tools/get-scala-commit-sha: [[: not found
    tools/get-scala-commit-sha: 17: tools/get-scala-commit-sha: Bad substitution

5. Use short hashes to enhance output readability.

6. Use branch name when available.

If the branch name is not used when the working directory is restored
after checkout out the parent commit we will be in a detached HEAD
state. Make a best effort to avoid that.

7. Ensure scaladoc copies are clean.

Remove previous copy of scaladoc to ensure consistent behaviour on runs
past the first.

8. Remove use of scaladoc-compare because the equivalent functionality is
provided when iterating the new files.

9. Improve message formatting.

10. Use $(...) instead of backticks for more legible code.

11. Pause after reporting missing old file.

Without this pause it was easy to miss the message when we had this
sequence of differences,

 * differing files
 * missing file
 * differing files

12. Report missing new files.

Along with reporting new files with no corresponding old file report the
complementary scenario.
---
 tools/scaladoc-diff | 100 ++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 73 insertions(+), 27 deletions(-)

(limited to 'tools')

diff --git a/tools/scaladoc-diff b/tools/scaladoc-diff
index 64dc025ecd..df0d1f3335 100755
--- a/tools/scaladoc-diff
+++ b/tools/scaladoc-diff
@@ -4,68 +4,114 @@
 # of the parent commit. No arguments.
 #
 
+set -e
 
-oldsha=$(git log -1 --format="%H" HEAD^)
-oldsha=${oldsha#g}
-oldsha=${oldsha:0:10}
+# opendiff for Mac OS X, meld for Ubuntu then default to other commands.
+displaydiff() {
+  case "$(uname -s)" in
 
-sha=`sh tools/get-scala-commit-sha`
-echo "parent commit sha: $oldsha. current commit sha: $sha"
+    Darwin)
+      if hash opendiff 2>/dev/null; then
+        echo opendiff "$@"
+        opendiff "$@"
+      else
+        echo diff "$@"
+        diff -y "$@" | less -N
+      fi
+    ;;
+
+    *)
+      if hash meld 2>/dev/null; then
+        echo meld "$@"
+        meld "$@"
+      elif hash gvimdiff 2>/dev/null; then
+        echo gvimdiff "$@"
+        gvimdiff "$@"
+      else
+        echo diff "$@"
+        diff -y "$@" | less -N
+      fi
+    ;;
+  esac
+}
+
+oldsha=$(git rev-parse --short HEAD^)
+
+# Use branch name defaulting to SHA1 when not available for example when in
+# detached HEAD state.
+sha=$(git symbolic-ref -q --short HEAD || git rev-parse --short HEAD)
+
+echo "parent commit sha  : $oldsha"
+echo "current commit sha : $sha"
 
 # create scaladoc for parent commit if not done already
 if [ ! -f "build/scaladoc-output-$oldsha.txt" ]
 then
   echo "making scaladoc for parent commit ($oldsha)"
-  git checkout HEAD^
+  git checkout -q $oldsha
   ant docs.lib -Dscaladoc.raw.output='yes' > build/scaladoc-output-$oldsha.txt
-  cp -r build/scaladoc/ build/scaladoc-${oldsha}
-  git checkout $sha
+  rm -rf build/scaladoc-${oldsha}
+  mv build/scaladoc build/scaladoc-${oldsha}
+  git checkout -q $sha
 fi
 
 # create scaladoc for current commit
 echo "making scaladoc for current commit ($sha)"
 ant docs.lib -Dscaladoc.raw.output='yes' > build/scaladoc-output-$sha.txt
-cp -r build/scaladoc/ build/scaladoc-${sha}
-echo "opendiff build/scaladoc-output-$oldsha.txt build/scaladoc-output-$sha.txt"
-opendiff build/scaladoc-output-$oldsha.txt build/scaladoc-output-$sha.txt
+rm -rf build/scaladoc-${sha}
+mv build/scaladoc build/scaladoc-${sha}
 
-echo "Comparing files..."
+# Allow script to continue when diff results in -1
+set +e
 
-difffile=build/scaladoc-diff-${sha}-$oldsha.txt
-sh tools/scaladoc-compare build/scaladoc-${sha}/ build/scaladoc-$oldsha/ &> $difffile
-open $difffile &
+displaydiff build/scaladoc-output-$oldsha.txt build/scaladoc-output-$sha.txt
 
 # Adapted from tools/scaladoc-compare
-echo "Comparing versions with difftool: build/scaladoc-${sha}/ build/scaladoc-$oldsha/"
+echo "Comparing versions with diff: build/scaladoc-${sha}/ build/scaladoc-$oldsha/"
 NEW_PATH=build/scaladoc-${sha}/
 OLD_PATH=build/scaladoc-$oldsha/
 
-FILES=`find $NEW_PATH -name '*.html.raw'`
-if [ "$FILES" == "" ]
+
+NEWFILES=$(find $NEW_PATH -name '*.html.raw')
+if [ "$NEWFILES" == "" ]
 then
   echo "No .html.raw files found in $NEW_PATH!"
   exit 1
 fi
 
-for NEW_FILE in $FILES
+for NEW_FILE in $NEWFILES
 do
   OLD_FILE=${NEW_FILE/$NEW_PATH/$OLD_PATH}
   if [ -f $OLD_FILE ]
   then
-    DIFF=`diff -q -w $NEW_FILE $OLD_FILE 2>&1`
+    DIFF=$(diff -q -w $NEW_FILE $OLD_FILE 2>&1)
     if [ "$DIFF" != "" ]
     then
-      opendiff $OLD_FILE $NEW_FILE > /dev/null
+      displaydiff $OLD_FILE $NEW_FILE > /dev/null
+
       echo "next [y\N]? "
       read -n 1 -s input
-
-      if [ "$input" == "N" ]
-      then exit 0
-      fi
+      if [ "$input" == "N" ]; then exit 0; fi
     fi
   else
-    echo -e "$NEW_FILE: No corresponding file (expecting $OLD_FILE)\n\n"
+    echo
+    echo "New file:                 : $NEW_FILE"
+    echo "No corresponding old file : $OLD_FILE"
+
+    echo "next [y\N]? "
+    read -n 1 -s input
+    if [ "$input" == "N" ]; then exit 0; fi
   fi
 done
 
-echo "Done."
+OLDFILES=$(find $OLD_PATH -name '*.html.raw')
+for OLD_FILE in $OLDFILES
+do
+  NEW_FILE=${OLD_FILE/$OLD_PATH/$NEW_PATH}
+  if [ ! -f $NEW_FILE ]
+  then
+    echo
+    echo "Old file:                 : $OLD_FILE"
+    echo "No corresponding new file : $NEW_FILE"
+  fi
+done
-- 
cgit v1.2.3