Document structure of upgrade-zulip-stage-2 more clearly.

scripts/lib/upgrade-zulip

@@ -50,9 +50,11 @@ try:
     unpack_zulip = os.path.realpath(os.path.join(os.path.dirname(__file__), 'unpack-zulip'))
     deploy_path = subprocess.check_output([unpack_zulip, tarball_path], preexec_fn=su_to_zulip)
 
+    # Chdir to deploy_path and then run upgrade-zulip-stage-2 from the
+    # new version of Zulip (having the upgrade logic run from the new
+    # version is much better for fixing bugs in the upgrade process).
     deploy_path = deploy_path.strip()
     os.chdir(deploy_path)
-
     subprocess.check_call(["./scripts/lib/upgrade-zulip-stage-2", deploy_path])
 
     logging.info("Deployment complete")

scripts/lib/upgrade-zulip-stage-2

@@ -1,4 +1,9 @@
 #!/usr/bin/env python2.7
+#
+# This script contains the actual logic for upgrading from an old
+# version of Zulip to the new version.  upgrade-zulip-stage-2 is
+# always run from the new version of Zulip, so any bug fixes take
+# effect on the very next upgrade.
 import subprocess
 import os
 import sys