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="[email protected]"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 [email protected] 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 <[email protected]>To: Serge Broslavsky <[email protected]>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 <[email protected]> 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 <[email protected]> wrote and on 2014-03-02 16:46:27, Serge Broslavsky <[email protected]> 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