diff --git a/pkgs/applications/audio/spotify/update.sh b/pkgs/applications/audio/spotify/update.sh
index 114245f6d46c..0e19ca1920b4 100755
--- a/pkgs/applications/audio/spotify/update.sh
+++ b/pkgs/applications/audio/spotify/update.sh
@@ -1,8 +1,31 @@
-channel="stable" # stable/candidate/edge
+#!/usr/bin/env nix-shell
+#! nix-shell -i bash -p curl jq git gnused gnugrep
+
+
+# executing this script without arguments will
+# - find the newest stable spotify version avaiable on snapcraft (https://snapcraft.io/spotify)
+# - read the current spotify version from the current nix expression
+# - update the nix expression if the versions differ
+# - try to build the updated version, exit if that fails
+# - give instructions for upstreaming
+
+# Please test the update manually before pushing. There have been errors before
+# and because the service is proprietary and a paid account is necessary to do
+# anything with spotify automatic testing is not possible.
+
+# As an optional argument you can specify the snapcraft channel to update to.
+# Default is `stable` and only stable updates should be pushed to nixpkgs. For
+# testing you may specify `candidate` or `edge`.
+
+
+channel="${1:-stable}" # stable/candidate/edge
 nixpkgs="$(git rev-parse --show-toplevel)"
 spotify_nix="$nixpkgs/pkgs/applications/audio/spotify/default.nix"
 
 
+#
+# find the newest stable spotify version avaiable on snapcraft
+#
 
 # create bash array from snap info
 snap_info=($(
@@ -12,38 +35,62 @@ snap_info=($(
 		'.revision,.download_sha512,.version,.last_updated'
 ))
 
+# "revision" is the actual version identifier on snapcraft, the "version" is
+# just for human consumption. Revision is just an integer that gets increased
+# by one every (stable or unstable) release.
 revision="${snap_info[0]}"
 sha512="${snap_info[1]}"
-version="${snap_info[2]}"
+upstream_version="${snap_info[2]}"
 last_updated="${snap_info[3]}"
 
-# find the last commited version
-version_pre=$(
-	git  grep 'version\s*=' HEAD "$spotify_nix" \
+echo "Latest $channel release is $upstream_version from $last_updated."
+
+#
+# read the current spotify version from the currently *committed* nix expression
+#
+
+current_nix_version=$(
+	grep 'version\s*=' "$spotify_nix" \
 	| sed -Ene 's/.*"(.*)".*/\1/p'
 )
 
-if [[ "$version_pre" = "$version" ]]; then
+echo "Current nix version: $current_nix_version"
+
+#
+# update the nix expression if the versions differ
+#
+
+if [[ "$current_nix_version" = "$upstream_version" ]]; then
 	echo "Spotify is already up ot date"
 	exit 0
 fi
 
-echo "Updating from ${version_pre} to ${version}, released on ${last_updated}"
+echo "Updating from ${current_nix_version} to ${upstream_version}, released on ${last_updated}"
 
-# search-andreplace revision, hash and version
+# search-and-replace revision, hash and version
 sed --regexp-extended \
 	-e 's/rev\s*=\s*"[0-9]+"\s*;/rev = "'"${revision}"'";/' \
-	-e 's/sha512\s*=\s*".{128}"\s*;/sha512 = "'"${sha512}"'";/' \
-	-e 's/version\s*=\s*".*"\s*;/version = "'"${version}"'";/' \
+	-e 's/sha512\s*=\s*"[^"]*"\s*;/sha512 = "'"${sha512}"'";/' \
+	-e 's/version\s*=\s*".*"\s*;/version = "'"${upstream_version}"'";/' \
 	-i "$spotify_nix" 
 
+#
+# try to build the updated version
+#
+
 if ! nix-build -A spotify "$nixpkgs"; then
 	echo "The updated spotify failed to build."
 	exit 1
 fi
 
+#
+# give instructions for upstreaming
+#
+
 git add "$spotify_nix"
-# show diff for review
-git diff HEAD
-# prepare commit message, but allow edit
-git commit --edit --message "spotify: $version_pre -> $version"
+# show changes for review
+git status
+echo 'Please review and test the changes (./result/bin/spotify).'
+echo 'Then stage the changes with `git add` and commit with:'
+# prepare commit message
+echo "git commit -m 'spotify: $current_nix_version -> $upstream_version'"