Resource: LCA14 Name: LCA14-106: jic - the CLI interface to JIRA for geeks Date: 03-03-2014 Speaker: Serge Broslavsky Video: https://www.youtube.com/watch?v=7QeKGkjx5HA

1. Mon-3-Mar, 12:10am, Serge Broslavsky
LCA14-106: jic - the CLI interface
to JIRA for geeks

2. JIRA Lingo
• Issue
– a bunch of fields with
their respective values
and an unique ID (e.g.
CARD-1, PMWG-2, etc)
• Project
– a collection of Issues
with the same project ID
(VIRT-1, VIRT-2, etc)
• Link
– a typed and directional
link between any two
Issues
• Structure
– a named hierarchy of
Issues built using one of
the Link types
• Scrum/Kanban Board
– a tabular representation
of a set of Issues with an
option to change Issue
states using drag'n'drop
• Dashboard
– a real-time report on a
group of Issues

3. Linaro’s JIRA Lingo
• Roadmap Project
– A JIRA project
containing Epics and
Cards
• Epic (RME)
– An Issue defining a huge
(>6mo) piece of work
approved by TSC/xSC
• Card (RMC)
– An Issue defining a big
(>3mo) piece of work
approved by OPSCOM
• Engineering Project
– A JIRA project for a team
• Engineering Card (EC)
– A stub Issue used to link
RMCs to EBPs
• Blueprint (EBP)
– An Issue defining a
feature to be
implemented
• Sub-Task (EST)
– An Issue used as a
TODO item for EBPs

4. Why do we use JIRA
• To document and track what we do
– features
– requests
– bugs (together with Bugzilla)
• To communicate the progress and the state of the work
– for each work item
– overall
• Because of its
– features
– good quality and support

5. It's a Web application:
– Away from your lovely terminal
– It hurts your eyes (not a green-on-black goodness)
– Forget about shell-scriptability (not accessible from a shell)
– You can't pipe data in and out of it
– It is slow (loads HTML, CSS, JavaScript, AJAXes data, only then
it displays your information)
– It is online only (no access to data when the network or the
server is down, no chance to udate your JIRA issues while on
the plane)
But is it that bad?
– Nope, it has a decent keyboard shortcut scheme!
Why does it hurt to use JIRA sometimes

6. • I prefer using right tools for each task
• Why would I want anyone to do otherwise?
• I love unix console
• It helps concentrating on the information itself
• I can’t stop writing software
• Engineers know why that feels so good
• Existing CLI JIRA tools are not matching my (and yours)
requirements
• Not git-like enough
• Too heavy (hint: Java…)
Why am I doing this?

7. • a CLI application (curses)
• gets information from arguments and invokes your editor when
needed
• authenticates securely (no clear text password stored)
• can represent major JIRA concepts (issue, link, structure, board) in
a textual format
• can create, edit, comment and transition issues
• can filter the output (i.e. show only issues matching some criteria)
• templatable output and input (including via pipes)
• can talk to pipes (both directions - in and out)
• outputs ANSI colored text (if asked to)
• can be used offline
What would be a proper JIRA UI

8. ✔ a CLI application (curses)
✔ gets information from arguments and invokes your editor when
needed
✔ authenticates securely using OAuth
✏ can represent major JIRA concepts (issue, link, structure, board) in
a textual format
✏ can create, edit, comment and transition issues
✏ templatable output and input (including via pipes)
⌛ can filter the output (i.e. show only issues matching some criteria)
⌛ can talk to pipes (both directions - in and out)
⌛ outputs ANSI colored text (if asked to)
⌛ can be used offline
jic - your friendly JIRA CLI

9. • Done in Python using JIRA’s REST API
• Initial version with the core functionality is developed by Serge
Broslavsky alone
• Goes to GitHub (https://github.com/ototo/jic) as soon as Issue
editing feature is complete (planning to do that at LCA)
• Project page placeholder has already been created at http://ototo.
github.io/jic/ - it will contain all the online documentation for the tool
• The goal is to release one version per month (same as for Linaro
releases) with quick fixes in between when needed
• Each new version will be developed in next branch, while the stable,
already released version will be on the tip of the master branch
Development

10. 1. See my assigned Issues
2. See an Issue in details
3. See an Issue in its hierarchy
4. Add a comment for an Issue
5. Edit a comment for an Issue
6. Transition an Issue
7. Edit an Issue (or a few Issues)
8. Create an Issue (or a few Issues)
9. Other
Engineer’s Use Cases

11. $ jic my
Query: assignee="serge.broslavsky@linaro.org"
You have 74 assigned issues:
EC: VIRT-76 - ENG: Xen - Linux Device Tree Editing - Open
EC: VIRT-75 - ENG: CI Bring-up: Xen - Open
EC: VIRT-74 - ENG: Xen - Multi-platform ARMv7 Binaries - Open
EC: VIRT-40 - Eng: Bootloader HYP mode support for ARMv8 - Open
EC: VIRT-39 - Eng: GDB stub for QEMU ARMv8 - Open
EC: VIRT-35 - Eng: Guest image howto for KVM ARMv8 - Open
EC: VIRT-34 - Eng: UEFI support for guests for KVM ARMv8 - Open
EC: VIRT-32 - Eng: Profiling support for KVM ARMv8 - Open
EC: VIRT-31 - Eng: Debugging support for KVM ARMv8 - Open
EC: VIRT-30 - Eng: ARMv8 KVM reliability and robustness - Closed / Duplicate
...
1. See my assigned resources
• An equivalent to jic list my assigned
• Other options:
• jic list my reported - to see what I’ve authored
• jic list my all - all the Issues related to me
• jic list firt.last@linaro.org all - other person’s Issues

12. 2. See an Issue in details
$ jic show PMO-57
Issue: PMO-57
Summary: JIC - JIRA Commandline tool
Type: Blueprint
Priority: Major
Status: Open
Date: 2013-11-01 16:12:16 UTC / 2013-09-16 15:44:26 UTC
From: Serge Broslavsky <serge.broslavsky@linaro.org>
To: Serge Broslavsky <serge.broslavsky@linaro.org>
Project: Linaro Project Management Office
URL: http://dev.cards.linaro.org/browse/PMO-57
h1. Rationale
...
• An equivalent to jic show body PMO-57
• Other options:
• jic show comments PMO-57 - to see Issue’s comments
• jic show history PMO-57 - to see Issue’s change history
• jic show all PMO-57 - to see all Issue’s information

13. 3. See an Issue in its hierarchy
$ jic tree PMO-57
EC: PMO-56 - JIRA Related Tools - Open
└─> is implemented by EBP: PMO-57 - JIC - JIRA Commandline tool - Open
├─> is implemented by EST: PMO-68 - Bulk edit/create of issues - Open
├─> is implemented by EST: PMO-65 - Transition issue - In Progress
├─> is implemented by EST: PMO-66 - Edit issue - In Progress
├─> is implemented by EST: PMO-67 - Create an issue - In Progress
├─> is implemented by EST: PMO-58 - List my issues - Resolved / Delivered
├─> is implemented by EST: PMO-59 - List others' issues - Resolved / Delivered
├─> is implemented by EST: PMO-60 - Show an issue - Resolved / Delivered
├─> is implemented by EST: PMO-61 - Show issue links - Resolved / Delivered
├─> is implemented by EST: PMO-62 - Show issue tree - Resolved / Fixed
├─> is implemented by EST: PMO-63 - Arbitrary JQL query - Resolved / Delivered
...
• An equivalent to jic tree both PMO-57
• Other options:
• jic tree up PMO-57 - to see the hierarchy towards parent
• jic tree down PMO-57 - to see the hierarchy towards children

14. 4. Add a comment for an issue
$ jic comment add PMO-57
# an editor is invoked here to get user’s input, which was “This is a comment”
The comment being added
> This is a comment.
Adding to PMO-57... Done.
$ jic show comments PMO-57
Issue: PMO-57
Summary: JIC - JIRA Commandline tool
======== Comments ========
# skipped the first comment for the presentation
[19200] On 2014-03-02 16:35:30, Serge Broslavsky <serge.broslavsky@linaro.org>
wrote:
> This is a comment.
• Each comment has an unique ID (shown in square brackets)

15. 5. Edit a comment for an Issue
$ jic comment edit PMO-57:19200
Getting comment: PMO-57:19200... Done.
# an editor is invoked, user edits the comment to ”This is an edited comment”
The comment PMO-57:19200 is being replaced with:
> This is an edited comment.
Replacing... Done.
$ jic show comments PMO-57
Issue: PMO-57
Summary: JIC - JIRA Commandline tool
======== Comments ========
# skipped the first comment for the presentation
[19200] On 2014-03-02 16:35:30, Serge Broslavsky <serge.broslavsky@linaro.org>
wrote and on 2014-03-02 16:46:27, Serge Broslavsky <serge.broslavsky@linaro.org>
updated:
> This is an edited comment.
• Each comment has an unique ID (shown in square brackets)
• Other option is:
• jic comment delete PMO-57:19200

16. 6. Transition an Issue
$ jic transition PMO-57
# an editor is invoked with all the available next states listed but commented out
# and user uncomments the line “Status: 4:Start Progress”
About to perform the following changes:
Issue: PMO-57
status = 4: Start Progress
Would you like to apply those changes? y
• Known issue: if transitioning also requires updating some fields at
the same time, the operation will fail
• This issue will be corrected together with the issue editing feature

17. $ jic edit PMO-57
# an editor (vim in this case) is invoked with JICML representation of the Issue
7. Edit an Issue (or a few Issues)
• editor (vim in this case) is responsible for formatting the JICML
• Being developed at the moment, to be completed at LCA-14.
Issue: PMO-57
Summary: JIC - JIRA Commandline tool
#Project: Linaro Project Management Office
#Issue Type: Blueprint
...
Implements: PMO-56: JIRA Related Tools
...
Description: {{{
h1. Rationale
To get engineering buy-in for JIRA, PMO has to provide an interface to JIRA
that would be similar to daily tools used by engineering people. One of the
good prototypes might be git.
...

18. 8. Create an Issue (or a few Issues)
$ jic create PMO-56 EBP EST
# an editor (vim in this case) is invoked with JICML representation of the Issue
• Next feature to be developed after editing is complete.
Issue: NEW-PMO-1
Summary:
#Project: Linaro Project Management Office
#Issue Type: Blueprint
...
Implements: PMO-56: JIRA Related Tools
...
Description: {{{
}}}
Issue: NEW-PMO-2
...
#Issue Type: Sub-Task
...

19. 9. Other
$ jic help
JIC v13.41.3 - JIRA CLI client for your convenience
Allows using JIRA without a mouse and a massive web browser.
Usage: jic <command> [<option> ...] [<arg> ...]
where <arg> is one or more issue IDs delimited by a space
and where command might be:
<no command specified>
is a synonym of "jic my"
...
• This command shows all the officially supported commands
• Project page at GitHub will also contain the online documentation
for the tool
• man support is also planned

20. More about Linaro Connect: http://connect.linaro.org
More about Linaro: http://www.linaro.org/about/
More about Linaro engineering: http://www.linaro.org/engineering/
Linaro members: www.linaro.org/members