README.md

   1 # org-jira mode
   2
   3 [![Join the chat at https://gitter.im/org-jira/Lobby](https://badges.gitter.im/org-jira/Lobby.svg)](https://gitter.im/org-jira/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
   4 [![MELPA](http://melpa.org/packages/org-jira-badge.svg)](http://melpa.org/#/org-jira)
   5
   6 Use Jira in Emacs org-mode.
   7
   8 ## TOC
   9
  10 <!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
  11 **Table of Contents**
  12
  13 - [org-jira mode](#org-jira-mode)
  14     - [TOC](#toc)
  15     - [Setup](#setup)
  16         - [Installation](#installation)
  17         - [Configuration](#configuration)
  18     - [Usage](#usage)
  19         - [Getting Started](#getting-started)
  20         - [Keybinds](#keybinds)
  21         - [Customization](#customization)
  22             - [Authorization workaround (NOT secure)](#authorization-workaround-not-secure)
  23         - [Optimizations](#optimizations)
  24             - [Optimizing available actions for status changes](#optimizing-available-actions-for-status-changes)
  25     - [About](#about)
  26         - [Maintainer](#maintainer)
  27         - [License](#license)
  28
  29 <!-- markdown-toc end -->
  30
  31
  32 ## Setup
  33 ### Installation
  34 To install, just grab it off of MELPA (ensure your ~/.emacs already
  35 has MELPA set up):
  36
  37 ```lisp
  38 (require 'package)
  39 (add-to-list 'package-archives '("melpa" . "http://melpa.milkbox.net/packages/") t)
  40 (package-initialize)
  41 ```
  42
  43 Then run `M-x package-install RET org-jira RET` and you're done!
  44 ### Configuration
  45 In your ~/.emacs, you should set the variable as such:
  46
  47 ```conf
  48 (setq jiralib-url "https://your-site.atlassian.net")
  49 ```
  50
  51 If you don't want to enter your credentials (login/password) each time
  52 you go to connect, you can add to your ~/.authinfo.gpg or ~/.authinfo
  53 file, in a format similar to:
  54
  55 ```conf
  56 machine your-site.atlassian.net login you@example.com password yourPassword port 80
  57 ```
  58 _Please note that in the authinfo file, port 443 should be specified
  59 if your jiralib-url is https._
  60
  61 ## Usage
  62 ### Getting Started
  63 org-jira mode is easy to use, to get started (after installing this
  64 library) try running `M-x org-jira-get-issues`.  You should see that
  65 it pulls in all issues that are assigned to you.
  66
  67 Following that, you can try out some of the org-jira mode commands by
  68 visiting one of the files (they're named after your Jira project code,
  69 for example, 'EX.org' for a project named 'EX').
  70 ### Keybinds
  71 Some of the important keybindings:
  72
  73 ```lisp
  74 (define-key org-jira-map (kbd "C-c pg") 'org-jira-get-projects)
  75 (define-key org-jira-map (kbd "C-c ib") 'org-jira-browse-issue)
  76 (define-key org-jira-map (kbd "C-c ig") 'org-jira-get-issues)
  77 (define-key org-jira-map (kbd "C-c ih") 'org-jira-get-issues-headonly)
  78 (define-key org-jira-map (kbd "C-c iu") 'org-jira-update-issue)
  79 (define-key org-jira-map (kbd "C-c iw") 'org-jira-progress-issue)
  80 (define-key org-jira-map (kbd "C-c in") 'org-jira-progress-issue-next)
  81 (define-key org-jira-map (kbd "C-c ia") 'org-jira-assign-issue)
  82 (define-key org-jira-map (kbd "C-c ir") 'org-jira-refresh-issue)
  83 (define-key org-jira-map (kbd "C-c iR") 'org-jira-refresh-issues-in-buffer)
  84 (define-key org-jira-map (kbd "C-c ic") 'org-jira-create-issue)
  85 (define-key org-jira-map (kbd "C-c ik") 'org-jira-copy-current-issue-key)
  86 (define-key org-jira-map (kbd "C-c sc") 'org-jira-create-subtask)
  87 (define-key org-jira-map (kbd "C-c sg") 'org-jira-get-subtasks)
  88 (define-key org-jira-map (kbd "C-c cc") 'org-jira-add-comment)
  89 (define-key org-jira-map (kbd "C-c cu") 'org-jira-update-comment)
  90 (define-key org-jira-map (kbd "C-c wu") 'org-jira-update-worklogs-from-org-clocks)
  91 (define-key org-jira-map (kbd "C-c tj") 'org-jira-todo-to-jira)
  92 (define-key org-jira-map (kbd "C-c if") 'org-jira-get-issues-by-fixversion)
  93 ```
  94
  95 ### Customization
  96 You can define your own streamlined issue progress flow as such:
  97
  98 ```lisp
  99 (defconst org-jira-progress-issue-flow
 100   '(("To Do" . "In Progress"
 101     ("In Progress" . "Done"))))
 102 ```
 103 or using typical Emacs customize options, as its a defcustom.
 104
 105 This will allow you to quickly progress an issue based on its current
 106 status, and what the next status should be.
 107
 108 If your Jira is set up to display a status in the issue differently
 109 than what is shown in the button on Jira, your alist may look like
 110 this (use the labels shown in the org-jira Status when setting it up,
 111 or manually work out the workflows being used through
 112 standard `C-c iw` options/usage):
 113
 114 ```lisp
 115 (defconst org-jira-progress-issue-flow
 116   '(("To Do" . "Start Progress")
 117     ("In Development" . "Ready For Review")
 118     ("Code Review" . "Done")
 119     ("Done" . "Reopen")))
 120 ```
 121
 122 #### Authorization workaround (NOT secure)
 123 If your Jira instance has disabled basic auth, you can still get in
 124 by copying your web browser's cookie (open up developer console, and
 125 right click and 'Copy request as cURL', then copy/paste the cookie
 126 into the jiralib-token variable):
 127
 128 ```lisp
 129 (defconst jiralib-token
 130   `("Cookie" . ,(format "__atl_path=...; studio.crowd.tokenkey=...")))
 131 ```
 132
 133 ### Optimizations
 134 It's possible some things in your Jira instance rarely if ever change - while org-jira
 135 will dynamically query everything as needed, it makes use of some
 136 variables/caching per-run of Emacs.  If you ever notice something was
 137 changed on the Jira setup level, you may have to restart your Emacs
 138 (or manually unset these variables).  By the same token, that makes it
 139 possible to hardcode some of these values yourself, so org-jira never
 140 needs to look them up.
 141
 142 Some samples may be:
 143
 144 #### Optimizing available actions for status changes
 145 Take time inspecting jiralib-available-actions-cache variable as you
 146 use org-jira, when you see the type of data it stores, you can then
 147 just define it yourself, as such, so repeated usage will not need to
 148 re-query the endpoints to get these lists:
 149
 150 ```lisp
 151 (defconst jiralib-available-actions-cache
 152   '(("To Do"
 153      ("71" . "Business Question")
 154      ("11" . "Start Progress"))
 155     ("Code Review"
 156      ("71" . "Business Question")
 157      ("91" . "Reject")
 158      ("171" . "Failed Peer Review")
 159      ("221" . "Done"))
 160     ("In Development"
 161      ("71" . "Business Question")
 162      ("21" . "Ready For Review")
 163      ("81" . "Reject")
 164      ("161" . "Stop Progress"))
 165     ("Done"
 166      ("71" . "Business Question")
 167      ("141" . "Re-open"))))
 168 ```
 169
 170 ## About
 171 ### Maintainer
 172
 173 You can reach me directly: Matthew Carter <m@ahungry.com>, or file an
 174 issue here on https://github.com/ahungry/org-jira.
 175
 176 ### License
 177
 178 GPLv3