Mon-3-Mar, 12:10am, Serge Broslavsky

LCA14-106: jic - the CLI interface to JIRA for geeks

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

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

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

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

• 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?

• 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

✔ 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

• 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

1. See my assigned Issues2. See an Issue in details3. See an Issue in its hierarchy4. Add a comment for an Issue5. Edit a comment for an Issue6. Transition an Issue7. Edit an Issue (or a few Issues)8. Create an Issue (or a few Issues)9. Other

Engineer’s Use Cases

$ jic myQuery: assignee="serge.broslavsky@linaro.org"You have 74 assigned issues:EC: VIRT-76 - ENG: Xen - Linux Device Tree Editing - OpenEC: VIRT-75 - ENG: CI Bring-up: Xen - OpenEC: VIRT-74 - ENG: Xen - Multi-platform ARMv7 Binaries - OpenEC: VIRT-40 - Eng: Bootloader HYP mode support for ARMv8 - OpenEC: VIRT-39 - Eng: GDB stub for QEMU ARMv8 - OpenEC: VIRT-35 - Eng: Guest image howto for KVM ARMv8 - OpenEC: VIRT-34 - Eng: UEFI support for guests for KVM ARMv8 - OpenEC: VIRT-32 - Eng: Profiling support for KVM ARMv8 - OpenEC: VIRT-31 - Eng: Debugging support for KVM ARMv8 - OpenEC: 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

2. See an Issue in details$ jic show PMO-57Issue: PMO-57Summary: JIC - JIRA Commandline toolType: BlueprintPriority: MajorStatus: OpenDate: 2013-11-01 16:12:16 UTC / 2013-09-16 15:44:26 UTCFrom: Serge Broslavsky <serge.broslavsky@linaro.org>To: Serge Broslavsky <serge.broslavsky@linaro.org>Project: Linaro Project Management OfficeURL: 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

3. See an Issue in its hierarchy$ jic tree PMO-57EC: 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

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-57Issue: PMO-57Summary: 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)

5. Edit a comment for an Issue$ jic comment edit PMO-57:19200Getting 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-57Issue: PMO-57Summary: 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

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 ProgressWould 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

$ 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.

...

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...

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

More about Linaro Connect: http://connect.linaro.orgMore about Linaro: http://www.linaro.org/about/

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