doc: improve ceph-backport.sh comment block

Signed-off-by: Nathan Cutler <ncutler@suse.com>

diff --git a/src/script/ceph-backport.sh b/src/script/ceph-backport.sh
index 70b3643cb105ac7734b2a233f80a21477d1a8703..e40c7559ab6195c57dcd94874e778c1aa06b5af7 100755 (executable)
--- a/src/script/ceph-backport.sh
+++ b/src/script/ceph-backport.sh
@@ -1,27 +1,26 @@
 #!/bin/bash -e
 #
-# ceph-backport.sh
+# ceph-backport.sh - Ceph backporting script
 #
-# Ceph backporting script
+# Credits: This script is based on work done by Loic Dachary
 #
-# Assumes you have forked ceph/ceph.git, cloned your fork, and are running the
-# script in the local clone!
+# With proper setup, this script takes care of opening the backport PR,
+# updating the corresponding backport tracker issue, and cross-linking the
+# backport PR with the tracker issue.
 #
-# With this script, backporting workflow for backport issue
-# http://tracker.ceph.com/issues/19206 (a jewel backport)
-# becomes something like this:
+# However, before you start, some setup is required. Please be patient and
+# read carefully, all the way through to the end of this comment block, without
+# skimming or skipping :-)
 #
-# git remote add ceph http://github.com/ceph/ceph.git
-# git fetch ceph
-# git checkout -b wip-19206-jewel ceph/jewel
-# git cherry-pick -x ...
-# ceph-backport.sh 19206 jewel
+# Instructions for setup
+# ----------------------
 #
-# The script takes care of opening the backport PR, updating the tracker issue,
-# and cross-linking the backport PR with the tracker issue.
+# It is strongly suggested to copy the latest version of the script (from
+# the "master" branch) into your PATH. In particular, do not use any version
+# of the script from a stable (named) branch such as "nautilus", as these
+# versions are not maintained. Only the version in master is maintained.
 #
-# However, before you start you will need to find the right values for
-# the following:
+# You will need to find the right values for the following:
 #
 # redmine_key     # "My account" -> "API access key" -> "Show"
 # redmine_user_id # "Logged in as foobar", click on foobar link, Redmine User ID
@@ -30,7 +29,7 @@
                   # ensure it has "Full control of private repositories" scope
 # github_user     # Your github username
 #
-# Once you have the actual values for these three variables, create a file
+# Once you have the actual values for the above variables, create a file
 # $HOME/bin/backport_common.sh with the following contents
 # 
 # redmine_key=[your_redmine_key]
@@ -38,7 +37,7 @@
 # github_token=[your_github_personal_access_token]
 # github_user=[your_github_username]
 #
-# you can also optionally add the remote repo's name in this file, like
+# You can also optionally add the remote repo's name in this file, like
 #
 # github_repo=[your_github_repo_name]
 #
@@ -49,6 +48,28 @@
 # filesystem, etc.). Without correct values for these four variables, this
 # script will not work!
 #
+# Instructions for use
+# --------------------
+#
+# Assumes you have forked ceph/ceph.git, cloned your fork, and are running the
+# script in the local clone!
+#
+# With this script, backporting workflow for backport issue
+# http://tracker.ceph.com/issues/19206 (a jewel backport)
+# becomes something like this:
+#
+# git remote add ceph http://github.com/ceph/ceph.git
+# git fetch ceph
+# git checkout -b wip-19206-jewel ceph/jewel
+# git cherry-pick -x ...
+# ceph-backport.sh 19206 jewel
+#
+# See http://tracker.ceph.com/projects/ceph-releases/wiki/HOWTO_backport_commits
+# for more info on cherry-picking.
+#
+# Happy backporting!
+# Nathan
+#
 source $HOME/bin/backport_common.sh
 
 function failed_required_variable_check () {