Merge pull request #4343 from apjanke/jira-readme

jira: add README.md

3 files changed, 79 insertions, 30 deletions

diff --git a/plugins/jira/README.md b/plugins/jira/README.md
new file mode 100644
index 000000000..efb8a743a
--- /dev/null
+++ b/plugins/jira/README.md
@@ -0,0 +1,64 @@
+#  Jira plugin  #
+
+CLI support for JIRA interaction
+
+##  Description  ##
+
+This plugin provides command line tools for interacting with Atlassian's [JIRA](https://www.atlassian.com/software/jira) bug tracking software.
+
+The interaction is all done through the web. No local installation of JIRA is necessary.
+
+In this document, "JIRA" refers to the JIRA issue tracking server, and `jira` refers to the command this plugin supplies.
+
+##  Usage  ##
+
+This plugin supplies one command, `jira`, through which all its features are exposed. Most forms of this command open a JIRA page in your web browser.
+
+```
+jira            # performs the default action
+
+jira new        # opens a new issue
+jira dashboard  # opens your JIRA dashboard
+jira reported [username]  # queries for issues reported by a user
+jira assigned [username]  # queries for issues assigned to a user
+jira ABC-123    # opens an existing issue
+jira ABC-123 m  # opens an existing issue for adding a comment
+```
+
+#### Debugging usage  ####
+
+These calling forms are for developers' use, and may change at any time.
+
+```
+jira dumpconfig   # displays the effective configuration
+```
+
+##  Setup  ##
+
+The URL for your JIRA instance is set by `$JIRA_URL` or a `.jira_url` file.
+
+Add a `.jira-url` file in the base of your project. You can also set `$JIRA_URL` in your `~/.zshrc` or put a `.jira-url` in your home directory. A `.jira-url` in the current directory takes precedence, so you can make per-project customizations.
+
+The same goes with `.jira-prefix` and `$JIRA_PREFIX`. These control the prefix added to all issue IDs, which differentiates projects within a JIRA instance.
+
+For example:
+
+```
+cd to/my/project
+echo "https://jira.atlassian.com" >> .jira-url
+```
+
+(Note: The current implementation only looks in the current directory for `.jira-url` and `.jira-prefix`, not up the path, so if you are in a subdirectory of your project, it will fall back to your default JIRA URL. This will probably change in the future though.)
+
+###  Variables  ###
+
+* `$JIRA_URL` - Your JIRA instance's URL
+* `$JIRA_NAME` - Your JIRA username; used as the default user for `assigned`/`reported` searches
+* `$JIRA_PREFIX` - Prefix added to issue ID arguments
+* `$JIRA_RAPID_BOARD` - Set to `true` if you use Rapid Board
+* `$JIRA_DEFAULT_ACTION` - Action to do when `jira` is called with no arguments; defaults to "new"
+
+
+### Browser ###
+
+Your default web browser, as determined by how `open_command` handles `http://` URLs, is used for interacting with the JIRA instance. If you change your system's URL handler associations, it will change the browser that `jira` uses.
diff --git a/plugins/jira/_jira b/plugins/jira/_jira
index b0ea658e2..03fe6a499 100644
--- a/plugins/jira/_jira
+++ b/plugins/jira/_jira
@@ -7,6 +7,7 @@ _1st_arguments=(
   'dashboard:open the dashboard'
   'reported:search for issues reported by a user'
   'assigned:search for issues assigned to a user'
+  'dumpconfig:display effective jira configuration'
 )
 
 _arguments -C \
diff --git a/plugins/jira/jira.plugin.zsh b/plugins/jira/jira.plugin.zsh
index 89559767f..341e23ec0 100644
--- a/plugins/jira/jira.plugin.zsh
+++ b/plugins/jira/jira.plugin.zsh
@@ -1,35 +1,11 @@
 # CLI support for JIRA interaction
 #
-# Setup: 
-#   Add a .jira-url file in the base of your project
-#   You can also set $JIRA_URL in your .zshrc or put .jira-url in your home directory
-#   A .jira-url in the current directory takes precedence. 
-#   The same goes with .jira-prefix and $JIRA_PREFIX.
-#
-#   For example:
-#     cd to/my/project
-#     echo "https://name.jira.com" >> .jira-url
-#
-# Variables:
-#  $JIRA_RAPID_BOARD     - set to "true" if you use Rapid Board
-#  $JIRA_DEFAULT_ACTION  - action to do when `jira` is called witn no args
-#                          defaults to "new"
-#  $JIRA_NAME            - Your JIRA username. Used as default for assigned/reported
-#  $JIRA_PREFIX          - Prefix added to issue ID arguments
-#
-#
-# Usage: 
-#   jira            # Performs the default action
-#   jira new        # opens a new issue
-#   jira reported [username]
-#   jira assigned [username]
-#   jira dashboard
-#   jira ABC-123    # Opens an existing issue
-#   jira ABC-123 m  # Opens an existing issue for adding a comment
+# See README.md for details
 
 : ${JIRA_DEFAULT_ACTION:=new}
 
 function jira() {
+  emulate -L zsh
   local action=${1:=$JIRA_DEFAULT_ACTION}
 
   local jira_url jira_prefix
@@ -63,6 +39,12 @@ function jira() {
   elif [[ "$action" == "dashboard" ]]; then
     echo "Opening dashboard"
     open_command "${jira_url}/secure/Dashboard.jspa"
+  elif [[ "$action" == "dumpconfig" ]]; then
+    echo "JIRA_URL=$jira_url"
+    echo "JIRA_PREFIX=$jira_prefix"
+    echo "JIRA_NAME=$JIRA_NAME"
+    echo "JIRA_RAPID_BOARD=$JIRA_RAPID_BOARD"
+    echo "JIRA_DEFAULT_ACTION=$JIRA_DEFAULT_ACTION"
   else
     # Anything that doesn't match a special action is considered an issue name
     local issue_arg=$action
@@ -84,15 +66,17 @@ function jira() {
 
 function _jira_url_help() {
   cat << EOF
-JIRA url is not specified anywhere.
+error: JIRA URL is not specified anywhere.
+
 Valid options, in order of precedence:
   .jira-url file
   \$HOME/.jira-url file
-  JIRA_URL environment variable
+  \$JIRA_URL environment variable
 EOF
 }
 
 function _jira_query() {
+  emulate -L zsh
   local verb="$1"
   local jira_name lookup preposition query
   if [[ "${verb}" == "reported" ]]; then
@@ -102,12 +86,12 @@ function _jira_query() {
     lookup=assignee
     preposition=to
   else
-    echo "not a valid lookup: $verb" >&2
+    echo "error: not a valid lookup: $verb" >&2
     return 1
   fi
   jira_name=${2:=$JIRA_NAME}
   if [[ -z $jira_name ]]; then
-    echo "JIRA_NAME not specified" >&2
+    echo "error: JIRA_NAME not specified" >&2
     return 1
   fi