c4d84f1b77ff120cf337cb6bd8fcc9d29ca04a14

Message

Merge pull request #4343 from apjanke/jira-readme

jira: add README.md

Diff

This diff is truncated to protect this page.

  1diff --git a/plugins/jira/README.md b/plugins/jira/README.md
  2new file mode 100644
  3index 0000000000000000000000000000000000000000..efb8a743a6e6c4d07c01f9ab79075c89d7de5a17
  4--- /dev/null
  5+++ b/plugins/jira/README.md
  6@@ -0,0 +1,64 @@
  7+#  Jira plugin  #
  8+
  9+CLI support for JIRA interaction
 10+
 11+##  Description  ##
 12+
 13+This plugin provides command line tools for interacting with Atlassian's [JIRA](https://www.atlassian.com/software/jira) bug tracking software.
 14+
 15+The interaction is all done through the web. No local installation of JIRA is necessary.
 16+
 17+In this document, "JIRA" refers to the JIRA issue tracking server, and `jira` refers to the command this plugin supplies.
 18+
 19+##  Usage  ##
 20+
 21+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.
 22+
 23+```
 24+jira            # performs the default action
 25+
 26+jira new        # opens a new issue
 27+jira dashboard  # opens your JIRA dashboard
 28+jira reported [username]  # queries for issues reported by a user
 29+jira assigned [username]  # queries for issues assigned to a user
 30+jira ABC-123    # opens an existing issue
 31+jira ABC-123 m  # opens an existing issue for adding a comment
 32+```
 33+
 34+#### Debugging usage  ####
 35+
 36+These calling forms are for developers' use, and may change at any time.
 37+
 38+```
 39+jira dumpconfig   # displays the effective configuration
 40+```
 41+
 42+##  Setup  ##
 43+
 44+The URL for your JIRA instance is set by `$JIRA_URL` or a `.jira_url` file.
 45+
 46+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.
 47+
 48+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.
 49+
 50+For example:
 51+
 52+```
 53+cd to/my/project
 54+echo "https://jira.atlassian.com" >> .jira-url
 55+```
 56+
 57diff --git a/plugins/jira/_jira b/plugins/jira/_jira
 58index b0ea658e2f3ac23079fb19166509667407741ae2..03fe6a4993fb1a92a2fb0fad73c56f03d3453cc7 100644
 59--- a/plugins/jira/_jira
 60+++ b/plugins/jira/_jira
 61@@ -7,6 +7,7 @@ _1st_arguments=(
 62   'dashboard:open the dashboard'
 63   'reported:search for issues reported by a user'
 64   'assigned:search for issues assigned to a user'
 65+  'dumpconfig:display effective jira configuration'
 66 )
 67 
 68 _arguments -C \
 69diff --git a/plugins/jira/jira.plugin.zsh b/plugins/jira/jira.plugin.zsh
 70index 89559767f86b684ea0e47a69ea363e94acf11d12..341e23ec0e5cc42ea7d0bf28ef0abc05425998d5 100644
 71--- a/plugins/jira/jira.plugin.zsh
 72+++ b/plugins/jira/jira.plugin.zsh
 73@@ -1,35 +1,11 @@
 74 # CLI support for JIRA interaction
 75 #
 76-# Setup: 
 77-#   Add a .jira-url file in the base of your project
 78-#   You can also set $JIRA_URL in your .zshrc or put .jira-url in your home directory
 79-#   A .jira-url in the current directory takes precedence. 
 80-#   The same goes with .jira-prefix and $JIRA_PREFIX.
 81-#
 82-#   For example:
 83-#     cd to/my/project
 84-#     echo "https://name.jira.com" >> .jira-url
 85-#
 86-# Variables:
 87-#  $JIRA_RAPID_BOARD     - set to "true" if you use Rapid Board
 88-#  $JIRA_DEFAULT_ACTION  - action to do when `jira` is called witn no args
 89-#                          defaults to "new"
 90-#  $JIRA_NAME            - Your JIRA username. Used as default for assigned/reported
 91-#  $JIRA_PREFIX          - Prefix added to issue ID arguments
 92-#
 93-#
 94-# Usage: 
 95-#   jira            # Performs the default action
 96-#   jira new        # opens a new issue
 97-#   jira reported [username]
 98-#   jira assigned [username]
 99-#   jira dashboard
100-#   jira ABC-123    # Opens an existing issue
101-#   jira ABC-123 m  # Opens an existing issue for adding a comment
102+# See README.md for details
103 
104 : ${JIRA_DEFAULT_ACTION:=new}
105 
106 function jira() {
107+  emulate -L zsh
108   local action=${1:=$JIRA_DEFAULT_ACTION}
109 
110   local jira_url jira_prefix
111@@ -63,6 +39,12 @@ function jira() {
112   elif [[ "$action" == "dashboard" ]]; then
113     echo "Opening dashboard"
114     open_command "${jira_url}/secure/Dashboard.jspa"
115+  elif [[ "$action" == "dumpconfig" ]]; then
116+    echo "JIRA_URL=$jira_url"
117+    echo "JIRA_PREFIX=$jira_prefix"
118+    echo "JIRA_NAME=$JIRA_NAME"
119+    echo "JIRA_RAPID_BOARD=$JIRA_RAPID_BOARD"
120+    echo "JIRA_DEFAULT_ACTION=$JIRA_DEFAULT_ACTION"
121   else
122     # Anything that doesn't match a special action is considered an issue name
123     local issue_arg=$action
124@@ -84,15 +66,17 @@ function jira() {
125 
126 function _jira_url_help() {
127   cat << EOF
128-JIRA url is not specified anywhere.
129+error: JIRA URL is not specified anywhere.
130+
131 Valid options, in order of precedence:
132   .jira-url file
133   \$HOME/.jira-url file
134-  JIRA_URL environment variable
135+  \$JIRA_URL environment variable
136 EOF
137 }
138 
139 function _jira_query() {
140+  emulate -L zsh
141   local verb="$1"
142   local jira_name lookup preposition query
143   if [[ "${verb}" == "reported" ]]; then
144@@ -102,12 +86,12 @@ function _jira_query() {
145     lookup=assignee
146     preposition=to
147   else
148-    echo "not a valid lookup: $verb" >&2
149+    echo "error: not a valid lookup: $verb" >&2
150     return 1
151   fi
152   jira_name=${2:=$JIRA_NAME}
153   if [[ -z $jira_name ]]; then
154-    echo "JIRA_NAME not specified" >&2
155+    echo "error: JIRA_NAME not specified" >&2
156     return 1
157   fi
158