document and improve developer scripts

- markdown docs were intentionally held back from prior PR to avoid
  merge conflict
- add -help usage notes to all scripts
- add sanity check against user running develop_brew_cask inside
  /usr/local/Library/Taps/phinze-cask/developer/bin and better explain that
- note everywhere that "brew update" is not safe when in "development mode"

HACKING.md

@@ -87,17 +87,44 @@ Formula definition.  Casks are defined differently than Formulae, which
 
 ## How Should I Set Up a Development Environment?
 
-When developing, one way to play with your changes is to symlink
-the `rubylib` folder to your Tap repository.
+Cask authors often work directly within the Homebrew directory
+under `/usr/local`.  For coding, that is usually not sufficient.
 
-```bash
-$ cd $(brew --prefix brew-cask)
-$ mv rubylib{,.orig}
-$ ln -s $(brew --prefix)/Library/Taps/phinze-cask/lib rubylib
-```
+We recommend the following:
 
-Now you can hack on homebrew-cask in the Tap and use the `brew cask` CLI
-like normal to interact with your latest code.
+1. Fork our repo: <https://github.com/phinze/homebrew-cask/fork>
+2. Clone a private copy of the repo:
+
+	```bash
+	git clone https://github.com/<username>/homebrew-cask.git
+	```
+
+3. Add the official repo as the `upstream` remote:
+
+	```bash
+	cd homebrew-cask
+	git remote add upstream https://github.com/phinze/homebrew-cask.git
+	```
+
+4. Now you have two copies of the homebrew-cask codebase on disk: the
+   released version in `/usr/local/Library/Taps/phinze-cask`, and a
+   development version in your private repo.  To symlink the `Casks`
+   and `rubylib` folders from `/usr/local/...` into your private repo,
+   run the following script:
+
+	```bash
+	/<path>/<to>/<private>/<repo>/developer/bin/develop_brew_cask
+	```
+   Now you can hack on your private repo, and use the `brew cask`
+   CLI like normal -- it will interact with your latest code.
+
+5. Important: while in development mode, you can't safely run
+   Homebrew's `brew update` command.  To switch back to production
+   mode, run
+
+	```bash
+	/<path>/<to>/<private>/<repo>/developer/bin/production_brew_cask
+	```
 
 ## Hanging out on IRC
 

RELEASING.md

@@ -19,22 +19,24 @@ down then floating in a brain somewhere.
 1. Do a git log since the last release to see what changed. You can scope it to
    `lib` to just pick up code changes and filter out Casks noise.
    Like this: `git log v0.25.0..HEAD lib`
-2. Bump the version, which is stored in the `brew-cask.rb` formula. Decide
+2. Optionally run `developer/bin/project_stats <previous-release-tag>` for
+   overall release stats.
+3. Bump the version, which is stored in the `brew-cask.rb` formula. Decide
    whether to bump minor or patch based on whether or not features were added.
-3. Populate the CHANGELOG with a new section for the release you are creating.
+4. Populate the CHANGELOG with a new section for the release you are creating.
    Follow the patterns used elsewhere in the file.
-4. Make a commit with CHANGELOG + version bump.
+5. Make a commit with CHANGELOG + version bump.
    Like this: `git commit -m 'cut v0.26.0'`
-5. Tag that commit, ensuring that you provide a message so we get an annotated
+6. Tag that commit, ensuring that you provide a message so we get an annotated
    tag.
    Like this: `git tag -m v0.26.0 v0.26.0`
-6. Push the commit and the tag: `git push --follow-tags`
-7. Hop to the GitHub project and click "Releases" then the link for your newly
+7. Push the commit and the tag: `git push --follow-tags`
+8. Hop to the GitHub project and click "Releases" then the link for your newly
    pushed tag. Click the "Edit Tag" button in the top right corner of that
    page.
-8. Paste the markdown summary from the CHANGELOG in the body of the release and
+9. Paste the markdown summary from the CHANGELOG in the body of the release and
    click "Publish Release".
-9. Rejoice! Have a :cookie:.
+10. Rejoice! Have a :cookie:.
 
 ## Things to Consider
 

developer/bin/develop_brew_cask

@@ -2,15 +2,30 @@
 #
 # develop_brew_cask
 #
-# symlink repo directories into homebrew cellar so that the
-# 'brew cask' command will use the current devel branch.
-#
-# Saves the production directories under new names.
-#
 
 set -e;              # exit on any uncaught error
 set +o histexpand;   # don't expand history expressions
 
+tap_subdir="Library/Taps/phinze-cask"
+
+if [[ $1 =~ ^-+h(elp)?$ ]]; then
+    printf "develop_brew_cask
+
+   Symlink private repo directories into Homebrew's Cellar, so
+   that the 'brew cask' command will use the current development
+   branch in your private repo.
+
+   Saves the production Homebrew directories under new names.
+
+   You can reverse this operation with 'production_brew_cask'.
+
+   Note: it is not safe to run 'brew update' while development
+   mode is in effect.
+
+"
+    exit
+fi
+
 script_dir="$(/usr/bin/dirname $0)"
 cd "$script_dir"
 
@@ -18,6 +33,13 @@ git_root="$(git rev-parse --show-toplevel)"
 brew_prefix="$(brew --prefix)"
 cellar_dir="$brew_prefix/Cellar/brew-cask"
 version_dir=$(/bin/ls "$cellar_dir/" | sort | tail -1)
+tap_dir="$brew_prefix/$tap_subdir"
+
+# sanity check
+if [[ $(/usr/bin/stat -L -f '%i' "$tap_dir") -eq $(/usr/bin/stat -L -f '%i' "$git_root") ]]; then
+    printf "\nERROR: run this script in your private repo, not inside Homebrew.\n"
+    exit 1;
+fi
 
 if [ -z "$version_dir" ]; then
     echo "Can't get version dir under $cellar_dir/"
@@ -26,19 +48,22 @@ fi
 cd "$cellar_dir/$version_dir"
 
 if [ -e "production_rubylib" ]; then
-    echo brew-cask is already set up for development
+    echo "brew-cask is already set up for development"
     exit 1
 else
     mv rubylib production_rubylib
     mv Casks   production_Casks
     ln -s "$git_root/Casks" .
     ln -s "$git_root/lib"   rubylib
-    cd "$brew_prefix/Library/Taps/phinze-cask"
+    cd "$tap_dir"
     mv lib   production_lib
     mv Casks production_Casks
     ln -s "$git_root/Casks" .
     ln -s "$git_root/lib"   .
-    echo brew-cask is now in development mode
+
+    echo "brew-cask is now in development mode"
+    echo "Note: it is not safe 'brew update' while in development mode"
+
 fi
 
 #

developer/bin/production_brew_cask

@@ -2,13 +2,25 @@
 #
 # production_brew_cask
 #
-# undo symlinks created by 'develop_brew_cask' so that
-# the 'brew cask' command will use only released code
-#
 
 set -e;              # exit on any uncaught error
 set +o histexpand;   # don't expand history expressions
 
+tap_subdir="Library/Taps/phinze-cask"
+
+if [[ $1 =~ ^-+h(elp)?$ ]]; then
+    printf "production_brew_cask
+
+   Undo all symlinks created by 'develop_brew_cask' so that
+   the 'brew cask' command will use only released code within
+   Homebrew.
+
+   After running this command it is safe to run 'brew update'.
+
+"
+    exit
+fi
+
 script_dir="$(/usr/bin/dirname $0)"
 cd "$script_dir"
 
@@ -16,6 +28,13 @@ git_root="$(git rev-parse --show-toplevel)"
 brew_prefix="$(brew --prefix)"
 cellar_dir="$brew_prefix/Cellar/brew-cask"
 version_dir=$(/bin/ls "$cellar_dir/" | sort | tail -1)
+tap_dir="$brew_prefix/$tap_subdir"
+
+# sanity check
+if [[ $(/usr/bin/stat -L -f '%i' "$tap_dir") -eq $(/usr/bin/stat -L -f '%i' "$git_root") ]]; then
+    printf "\nERROR: run this script in your private repo, not inside Homebrew.\n"
+    exit 1;
+fi
 
 if [ -z "$version_dir" ]; then
     echo "Can't get version dir under $cellar_dir/"
@@ -27,13 +46,14 @@ if [ -e "production_rubylib" ]; then
     rm rubylib Casks
     mv production_rubylib rubylib
     mv production_Casks   Casks
-    cd "$brew_prefix/Library/Taps/phinze-cask"
+    cd "$tap_dir"
     rm lib Casks
     mv production_lib   lib
     mv production_Casks Casks
-    echo brew-cask is now in production mode
+    echo "brew-cask is now in production mode"
+    echo "It is safe to run 'brew update'"
 else
-    echo brew-cask is already set up for production
+    echo "brew-cask is already set up for production"
     exit 1
 fi