Merge remote-tracking branch 'github/master'HEADmaster

3 files changed, 92 insertions, 40 deletions

diff --git a/plugins/jira/README.md b/plugins/jira/README.md
index d78ea15a4..f6e2e26f4 100644
--- a/plugins/jira/README.md
+++ b/plugins/jira/README.md
@@ -1,46 +1,68 @@
-#  Jira plugin  #
+# Jira plugin
 
-CLI support for JIRA interaction
+This plugin provides command line tools for interacting with Atlassian's [JIRA](https://www.atlassian.com/software/jira) bug tracking software.
 
-##  Description  ##
+To use it, add `jira` to the plugins array in your zshrc file:
 
-This plugin provides command line tools for interacting with Atlassian's [JIRA](https://www.atlassian.com/software/jira) bug tracking software.
+```zsh
+plugins=(... jira)
+```
 
 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  ##
+## 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.
 
 ## Commands
 
-| Command       | Description                                               |
-| :------------ | :-------------------------------------------------------- |
-| `jira`        | Performs the default action                               |
-| `jira new`    | Opens a new Jira issue dialogue                           |
-| `jira ABC-123`   | Opens an existing issue                                |
-| `jira ABC-123 m` | Opens an existing issue for adding a comment           |
-| `jira dashboard [rapid_view]` |  # opens your JIRA dashboard              |
-| `jira mine`   | Queries for your own issues                               |
-| `jira tempo`  | Opens your JIRA Tempo                                     |
-| `jira reported [username]`  | Queries for issues reported by a user       |
-| `jira assigned [username]`  | Queries for issues assigned to a user       |
-| `jira branch` | Opens an existing issue matching the current branch name  |
+`jira help` or `jira usage` will print the below usage instructions
+
+| Command                       | Description                                              |
+| :---------------------------- | :------------------------------------------------------- |
+| `jira`                        | Performs the default action                              |
+| `jira new`                    | Opens a new Jira issue dialogue                          |
+| `jira ABC-123`                | Opens an existing issue                                  |
+| `jira ABC-123 m`              | Opens an existing issue for adding a comment             |
+| `jira project ABC`            | Opens JIRA project summary                               |
+| `jira dashboard [rapid_view]` | Opens your JIRA dashboard                                |
+| `jira mine`                   | Queries for your own issues                              |
+| `jira tempo`                  | Opens your JIRA Tempo                                    |
+| `jira reported [username]`    | Queries for issues reported by a user                    |
+| `jira assigned [username]`    | Queries for issues assigned to a user                    |
+| `jira branch`                 | Opens an existing issue matching the current branch name |
+| `jira help`                   | Prints usage instructions                                |
 
 
 ### Jira Branch usage notes
 
-The branch name may have prefixes ending in "/": "feature/MP-1234", and also suffixes 
+The branch name may have prefixes ending in "/": "feature/MP-1234", and also suffixes
 starting with "_": "MP-1234_fix_dashboard". In both these cases, the issue opened will be "MP-1234"
 
 This is also checks if the prefix is in the name, and adds it if not, so: "MP-1234" opens the issue "MP-1234",
 "mp-1234" opens the issue "mp-1234", and "1234" opens the issue "MP-1234".
 
+If your branch naming convention deviates, you can overwrite the jira_branch function to determine and echo the Jira issue key yourself.
+Define a function `jira_branch` after sourcing `oh-my-zsh.sh` in your `.zshrc`.
+Example:
+```zsh
+# Determine branch name from naming convention 'type/KEY-123/description'.
+function jira_branch() {
+  # Get name of the branch
+  issue_arg=$(git rev-parse --abbrev-ref HEAD)
+  # Strip prefixes like feature/ or bugfix/
+  issue_arg=${issue_arg#*/}
+  # Strip suffixes like /some-branch-description
+  issue_arg=${issue_arg%%/*}
+  # Return the value
+  echo $issue_arg
+}
+```
 
 
-#### Debugging usage  ####
+#### Debugging usage
 
 These calling forms are for developers' use, and may change at any time.
 
@@ -48,7 +70,7 @@ These calling forms are for developers' use, and may change at any time.
 jira dumpconfig   # displays the effective configuration
 ```
 
-##  Setup  ##
+## Setup
 
 The URL for your JIRA instance is set by `$JIRA_URL` or a `.jira_url` file.
 
@@ -65,7 +87,7 @@ 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  ###
+### Variables
 
 * `$JIRA_URL` - Your JIRA instance's URL
 * `$JIRA_NAME` - Your JIRA username; used as the default user for `assigned`/`reported` searches
@@ -76,6 +98,6 @@ echo "https://jira.atlassian.com" >> .jira-url
 * `$JIRA_TEMPO_PATH` - Your JIRA tempo url path; defaults to "/secure/Tempo.jspa"
 
 
-### Browser ###
+### 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 0e37b7e9d..617a3e501 100644
--- a/plugins/jira/_jira
+++ b/plugins/jira/_jira
@@ -5,12 +5,14 @@ local -a _1st_arguments
 _1st_arguments=(
   'new:create a new issue'
   'mine:open my issues'
+  'project:open the project'
   'dashboard:open the dashboard'
   'tempo:open the tempo'
   'reported:search for issues reported by a user'
   'assigned:search for issues assigned to a user'
   'branch:open the issue named after the git branch of the current directory'
   'dumpconfig:display effective jira configuration'
+  'help:print usage help to stdout'
 )
 
 _arguments -C \
diff --git a/plugins/jira/jira.plugin.zsh b/plugins/jira/jira.plugin.zsh
index b6ee9f100..0c90544d5 100644
--- a/plugins/jira/jira.plugin.zsh
+++ b/plugins/jira/jira.plugin.zsh
@@ -2,6 +2,46 @@
 #
 # See README.md for details
 
+function _jira_usage() {
+cat <<EOF
+jira                            Performs the default action
+jira new                        Opens a new Jira issue dialogue
+jira ABC-123                    Opens an existing issue
+jira ABC-123 m                  Opens an existing issue for adding a comment
+jira project ABC                Opens JIRA project summary
+jira dashboard [rapid_view]     Opens your JIRA dashboard
+jira mine                       Queries for your own issues
+jira tempo                      Opens your JIRA Tempo
+jira reported [username]        Queries for issues reported by a user
+jira assigned [username]        Queries for issues assigned to a user
+jira branch                     Opens an existing issue matching the current branch name
+EOF
+}
+
+# If your branch naming convention deviates, you can partially override this plugin function
+# to determine the jira issue key based on your formatting.
+# See https://github.com/ohmyzsh/ohmyzsh/wiki/Customization#partially-overriding-an-existing-plugin
+function jira_branch() {
+  # Get name of the branch
+  issue_arg=$(git rev-parse --abbrev-ref HEAD)
+  # Strip prefixes like feature/ or bugfix/
+  issue_arg=${issue_arg##*/}
+  # Strip suffixes starting with _
+  issue_arg=(${(s:_:)issue_arg})
+  # If there is only one part, it means that there is a different delimiter. Try with -
+  if [[ ${#issue_arg[@]} = 1 && ${issue_arg} == *-* ]]; then
+    issue_arg=(${(s:-:)issue_arg})
+    issue_arg="${issue_arg[1]}-${issue_arg[2]}"
+  else
+    issue_arg=${issue_arg[1]}
+  fi
+  if [[ "${issue_arg:l}" = ${jira_prefix:l}* ]]; then
+    echo "${issue_arg}"
+  else
+    echo "${jira_prefix}${issue_arg}"
+  fi
+}
+
 function jira() {
   emulate -L zsh
   local action jira_url jira_prefix
@@ -44,9 +84,14 @@ function jira() {
     open_command "${jira_url}/secure/CreateIssue!default.jspa"
   elif [[ "$action" == "assigned" || "$action" == "reported" ]]; then
     _jira_query ${@:-$action}
+  elif [[ "$action" == "help" || "$action" == "usage" ]]; then
+    _jira_usage
   elif [[ "$action" == "mine" ]]; then
     echo "Opening my issues"
     open_command "${jira_url}/issues/?filter=-1"
+  elif [[ "$action" == "project" ]]; then
+    echo "Opening project"
+    open_command "${jira_url}/jira/software/c/projects/${2}/summary"
   elif [[ "$action" == "dashboard" ]]; then
     echo "Opening dashboard"
     if [[ "$JIRA_RAPID_BOARD" == "true" ]]; then
@@ -74,24 +119,7 @@ function jira() {
     # but `branch` is a special case that will parse the current git branch
     local issue_arg issue
     if [[ "$action" == "branch" ]]; then
-      # Get name of the branch
-      issue_arg=$(git rev-parse --abbrev-ref HEAD)
-      # Strip prefixes like feature/ or bugfix/
-      issue_arg=${issue_arg##*/}
-      # Strip suffixes starting with _
-      issue_arg=(${(s:_:)issue_arg})
-      # If there is only one part, it means that there is a different delimiter. Try with -
-      if [[ ${#issue_arg[@]} = 1 && ${issue_arg} == *-* ]]; then
-        issue_arg=(${(s:-:)issue_arg})
-        issue_arg="${issue_arg[1]}-${issue_arg[2]}"
-      else
-        issue_arg=${issue_arg[1]}
-      fi
-      if [[ "${issue_arg:l}" = ${jira_prefix:l}* ]]; then
-        issue="${issue_arg}"
-      else
-        issue="${jira_prefix}${issue_arg}"
-      fi
+      issue=$(jira_branch)
     else
       issue_arg=${(U)action}
       issue="${jira_prefix}${issue_arg}"