Add some release script comments

scripts/release/Makefile.linux

@@ -22,6 +22,8 @@ build_releases:
 
 	@echo "======>> committing generated files"
 	git add -A .
+# skip comitting files if there are no generated files
+# if prerelease process was a no-op
 	if ! git diff-index --quiet HEAD --; \
 	then \
 		git commit --author 'Nomad Release bot <nomad@hashicorp.com>' \

scripts/release/docker-build-all

@@ -1,11 +1,39 @@
 #!/usr/bin/env bash
 
+# A script for building Linux and Windows nomad release binaries inside Docker
+#
+# This is a helper script file that is expected to be invoked
+# within a docker container with an image created with the Dockerfile present on this directory.
+#
+# A sample way of invoking the script is
+# ```
+# docker run --rm \
+#        -v $(pwd)/.git:/tmp/nomad-git:ro \
+#        -v /tmp/generated-repo:/tmp/artifacts:rw \
+#        -e "PRERELEASE_TARGET=${PRERELEASE_TARGET}" \
+#        -e "RELEASE_TARGET=${RELEASE_TARGET}" \
+#        -e "NOMAD_VERSION=${NOMAD_VERSION}" \
+#        nomad-builder:latest \
+#        /tmp/scripts/docker-build-all
+# ```
+# Namely the script takes the following arguments:
+# * `/tmp/nomad-git` path being a read-only .git directory with HEAD being the sha to be released
+# * `NOMAD_VERSION` env-var being the release version to be cut (e.g. `0.9.1-rc1`)
+# * `PRERELEASE_TARGET` env-var being the prerelease make target, typically `prerelease`.  Use `help` to skip `prerelease` step
+# * `RELEASE_TARGET` env-var being the release make target, typically `release`.
+#
+#
+# The script would then run prerelease steps, commits any generated files, and build all binary files
+# and stores them to `/tmp/artifacts/repo`.
+
 set -o errexit
 set -o xtrace
 
 cp -r /tmp/nomad-git /opt/gopath/src/github.com/hashicorp/nomad/.git
 
 cd /opt/gopath/src/github.com/hashicorp/nomad
+
+# checkout directory from .git and ensures a prestine state
 git checkout .
 
 make -f ./scripts/release/Makefile.linux \

scripts/release/mac-remote-build

@@ -1,5 +1,21 @@
 #!/usr/bin/env bash
 
+# A script for building macOS binary on a remote macOS host
+#
+# The helper is expected to be invoked with nomad repo as a first argument, e.g.
+# `mac-remote-build ~/go/src/github.com/hashicorp/nomad`.
+#
+# The repository is required to have a HEAD with all generated files and udpated version committed.
+#
+# The script runs a host on `sharedmac-bot` host (assumes a corresponding entry in ~/.ssh/config).
+# `REMOTE_MACOS_HOST` envvar can be set to point to another macOS host
+#
+# The script operates by creating a temporary workspace in the remote host to
+# contain a clean go installation and gopath with the repository content.
+# It should install all dependencies worth pinning, and *not* use system binaries
+# that may influence the integrity of the release.
+#
+
 set -o errexit
 
 REPO="$1"
@@ -8,6 +24,7 @@ RELEASE_TARGET="${2:-release}"
 if [[ -z "${REPO}" ]]
 then
     echo "repo path is required"
+    echo "Usage: $0 <repo_path>"
     exit 1
 fi