From e60605eb0ecc435355e43577beaa28e8f96c7724 Mon Sep 17 00:00:00 2001 From: Roland Walker Date: Sat, 18 Jan 2014 10:34:40 -0500 Subject: [PATCH] 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 | 45 ++++++++++++++++++++++++------ RELEASING.md | 18 ++++++------ developer/bin/develop_brew_cask | 41 +++++++++++++++++++++------ developer/bin/production_brew_cask | 32 +++++++++++++++++---- 4 files changed, 105 insertions(+), 31 deletions(-) diff --git a/HACKING.md b/HACKING.md index f8c359f05f..80710001e9 100644 --- a/HACKING.md +++ b/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: +2. Clone a private copy of the repo: + + ```bash + git clone https://github.com//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 + /////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 + /////developer/bin/production_brew_cask + ``` ## Hanging out on IRC diff --git a/RELEASING.md b/RELEASING.md index f8ae43e1c2..e4ee0393ed 100644 --- a/RELEASING.md +++ b/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 ` 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 diff --git a/developer/bin/develop_brew_cask b/developer/bin/develop_brew_cask index baaff20615..8e64864926 100755 --- a/developer/bin/develop_brew_cask +++ b/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 # diff --git a/developer/bin/production_brew_cask b/developer/bin/production_brew_cask index 969116ddf4..c6b8ef37f2 100755 --- a/developer/bin/production_brew_cask +++ b/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