Good localtime,
I'm glad to present you an excerpt from the jic CLI specification document I'm working on, which covers a new high level `frontend` mode, which supplements the previously presented `plumbing` mode.
It was created based on the feedback I've received during KWG/PMWG sprint in Le Mans two weeks ago.
I would like to get some feedback from you to confirm that this mode covers all the essential most frequent operations engineers will be using for their daily operations in the way that is matching your expectations.
I'll be waiting for your feedback till 28 July 2014 when I'll continue working on its implementation for the next version of jic.
-------- 8< -------- 8< -------- 8< -------- 8< --------
2. CLI STRUCTURE
To allow both - having a concise and easy to learn interface for the most frequent operations and a powerful but requiring more time to learn one, jic has modal command line interface with the following two modes:
1. Front end - the concise but limited one 2. Plumbing - the powerful but verbose one
It is possible to choose which one of the above will be the default one and switching between the two is done using the following switches:
--frontend --plumbing
Mode setting switch should be on the first place after jic's name as it defines how all the following switches and arguments are going to be interpreted.
Examples:
# let's assume for these examples that the default mode is # configured to be frontend.
# list issues reported by the user $ jic list reported
# list issues assigned to the user using a symlinked jic $ jls assigned
# add new command 'my week' $ jic --plumbing command add <<EOF my week,wee,we,wk,w plumbing:report generate MyWeekly -1w EOF
To set the default mode the following option should be changed:
Name: cli.mode Values: `frontend`, `plumbing` Default value: `plumbing`
That can be done using the following commands:
# set `frontend` to be the default mode $ jic --plumbing configuration set cli.mode frontend
# set `plumbing` to be the default mode $ jic --plumbing configuration set cli.mode plumbing
Alternative and more convenient way of using frontend commands is using symbolic links pointing to jic with their names matching the frontend commands defined. In this case the mode is set to be `frontend` regardless the default mode in configuration. Adding an explicit `--plumbing` switch in this case will however result in `plumbing` mode being selected.
After setting default mode to `plumbing` and adding proper symlinks for `frontend` mode commands, it is possible to use both modes with no need to explicitly specify each mode:
# access `plumbing` mode commands $ jic issue tree PMWG-100
# access `frontend` mode commands $ jadd PMWG-101 -m 'This comment is added using frontend mode!'
2.1. Frontend mode CLI structure
This mode is fully defined by the commands defined in the configuration file. To help users being productive without a need to spend lots of time reading through the plumbing commands' documentation and building their own frontend mode CLI, jic comes with a set of pre-configured commands that are listed below.
The structure of frontend mode command line:
$ jic word [word...] [<switches>] args
Preconfigured commands:
All the pre-configured `frontend` mode commands are listed below:
jadd add a comment
jedc edit a comment
jdel delete a comment
jsh [comments,history,links,worklog,all] show JIRA issues
jls [assigned,reported] list JIRA issues
jcr (sub-task,blueprint) create JIRA issues
jed edit JIRA issues
jtr transition JIRA issues
jwt log time spent on an issue
jul [depends,implements' unlink issues
Those are described in more details in the following sub-chapters.
2.1.1. Add comments
$ jadd [<issue_key> [<issue_key>...]] [-e] [-k] [-m <message>]
Adds comments, one per issue specified, using the text provided: - by `-m` switch is present; - using an editor (if `-e` is specified); - from stdin if no parameters are specified.
If `-k` switch is specified, issue keys for the issues to be processed are also read using the same method - all the lines of text till the first empty line will be parsed as a space or comma separated list of issue keys.
Examples:
# add a comment using an editor $ jadd CARD-100 -e
# add a comment for two cards using the message provided $ jadd CARD-100 CARD-101 -m 'This is\na multiline message'
# add a comment using stdin $ echo 'This is\na multiline comment' | jadd CARD-100
# add a comment into a set of cards $ jadd -k <<EOF CARD-100, CARD-101 CARD-102
This is a folded comment that will be added for the issues that are listed above. EOF
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF # define command aliases (the first one being the name of the # command) jadd,add,ad,a
# list allowed options e,k,m
# what does this command mean # possible types are: # plumbing for mapping to a plumbing command # frontend for mapping to a frontend command # python for defining a function that implements the # command plumbing:comments add $keys $args
EOF
which is an equivalent of:
$ jic --plumbing command add jadd,add,ad,a e,k,m \ 'plumbing:comments add $keys $args'
2.1.2. Edit comments
$ jedc [<issue_key:cmt_id[,<cmt_id>...>...]] [-e] [-k] [-m <message>]
Edits comments using the text provided: - by `-m` switch is present; - using an editor (if `-e` is specified); - from stdin if no parameters are specified.
If `-k` switch is specified, issue keys and comment ids for the comments to be processed are also read using the same method - all the lines of text till the first empty line will be parsed as a space or comma separated list of issue keys and comment ids.
Examples:
# edit a comment using an editor $ jedc CARD-100:2345 -e
# edit two comments for two cards using the message provided $ jedc CARD-100:2345 CARD-101:2445 -m 'This is a message'
# edit a comment using stdin $ echo 'This is\na multiline comment' | jedc CARD-100:2345
# edit a set of comments for a few cards $ jadd -k <<EOF CARD-100:2345,2346 CARD-101:3425 CARD-102:3446
This is the text that will replace the existing comments whose ids are listed above. EOF
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF jedc,editc,edic,edc,ec e,k,m plumbing:comments edit $keys $args EOF
2.1.3. Delete comments
$ jdel [<issue_key:cmt_id[,<cmt_id>...>...]] [-e] [-k]
Delete comments whose ids are specified using: - using an editor (if `-e` is specified); - from stdin if no parameters are specified.
If `-k` switch is specified, issue keys and comment ids for the comments to be deleted are read from stdin - all the lines of text till the first empty line will be parsed as a space or comma separated list of issue keys and comment ids.
Examples:
# delete a comment using an editor to edit the list of # issues and comment ids $ jdel CARD-100:2345 -e
# delete two comments for two cards using the message provided $ jdel CARD-100:2345 CARD-101:2346
# edit a set of comments for a few cards $ jdel -k <<EOF CARD-100:2345,2346 CARD-101:3425 CARD-102:3446 EOF
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF jdel,delete,delet,dele,del,de,d e,k plumbing:comments delete $keys $args EOF
2.1.4. Show issue (essential)
$ jsh [<issue_key> [<issue_key>...]] [-k]
Show essential issue information (fields).
Examples:
# show an issue $ jsh CARD-100
# show issues whose keys are provided using stdin $ echo 'CARD-100 CARD-101' | jsh
# show issues whose keys are provided using stdin and edited # using an editor $ jsh -e <<EOF CARD-100 CARD-101 EOF
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF jsh,show,sho,sh,s k plumbing:issue show -p fields $keys $args EOF
2.1.5. Show issue comments
$ jsh comments [<issue_key> [<issue_key>...]] [-k]
Show issue comments.
Examples:
# show issue's comments $ jsh comments CARD-100
# show comments for the issues whose keys are provided using # stdin $ echo 'CARD-100 CARD-101' | jsh c
# show comments for the issues whose keys are provided using # stdin and edited using an editor $ jsh comm -e <<EOF CARD-100 CARD-101 EOF
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF jsh,show,sho,sh,s comments,comment,commen,comme,comm,com,cmts,cmt,co,c k plumbing:issues show -p comments $keys $args EOF
2.1.6. Show issue (history)
$ jsh history [<issue_key> [<issue_key>...]] [-k]
Show issue change history.
Examples:
# show issue's change history $ jsh history CARD-100
# show change history for the issues whose keys are provided # using stdin $ echo 'CARD-100 CARD-101' | jsh h
# show change history for the issues whose keys are provided # using stdin and edited using an editor $ jshh -e <<EOF CARD-100 CARD-101 EOF
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF jsh,show,sho,sh,s history,histor,histo,hist,his,hi,h k plumbing:issues show -p history $keys $args EOF
2.1.7. Show issue (links)
$ jsh links [<issue_key> [<issue_key>...]] [-k]
Show issue links.
Examples:
# show issue's links $ jsh links CARD-100
# show links for the issues whose keys are provided # using stdin $ echo 'CARD-100 CARD-101' | jsh l
# show links for the issues whose keys are provided using # stdin and edited using an editor $ jsh l -e <<EOF CARD-100 CARD-101 EOF
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF jsh,show,sho,sh,s links,link,lin,lnk,li,ln,l k plumbing:issues show -p links $keys $args EOF
2.1.8. Show issue (worklog)
$ jsh worklog [<issue_key> [<issue_key>...]] [-k]
Show essential issue information (fields).
Examples:
# show issue's worklog $ jsh worklog CARD-100
# show worklogs for the issues whose keys are provided # using stdin $ echo 'CARD-100 CARD-101' | jsh w
# show worklogs for the issues whose keys are provided using # stdin and edited using an editor $ jsh w -e <<EOF CARD-100 CARD-101 EOF
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF jsh,show,sho,sh,s worklog,worklo,workl,work,wor,wo,w k plumbing:issues show -p worklog $keys $args EOF
2.1.9. Show issue (all information)
$ jsh all [<issue_key> [<issue_key>...]] [-k]
Show essential issue information (fields).
Examples:
# show all issue's information $ jsh all CARD-100
# show all information for the issues whose keys are provided # using stdin $ echo 'CARD-100 CARD-101' | jsh a
# show all information for the issues whose keys are # provided using stdin and edited using an editor $ jsh a -e <<EOF CARD-100 CARD-101 EOF
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF jsh,show,sho,sh,s all,al,a k plumbing:issues show -p all $keys $args EOF
2.1.10. List my assigned issues
$ jls assigned
Show list of the issues assigned to the user.
Examples:
# list all assigned issues $ jls assigned
# list all assigned issues using shortened form $ jls a
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF jls,list,lis,li,ls,l assigned,assigne,assign,assig,assi,ass,as,a k plumbing:issues list -f 'assigned=$me' $keys $args EOF
2.1.11. List my reported issues
$ jls reported
Show list of the issues reported by the user.
Examples:
# list all reported issues $ jls reported
# list all reported issues using shortened form $ jls r
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF jls,list,lis,li,ls,l reported,reporte,report,repor,repo,rep,re,r k plumbing:issues list -f 'reported=$me' $keys $args EOF
2.1.12. Create a new sub-task
$ jcr sub-task [<parent_issue_keys>] [-k] [-e] [-n <number>]
Create a new sub-task.
Examples:
# create a new sub-task in PMWG project for PMWG-100 using # an editor to get summary from the user $ jcr sub-task CARD-100 PMWG -e
# create a new sub-task in KWG project for KWG-100 using # stdin to get summary from the user $ echo 'Summary for a new sub-task' | jcr-st CARD-100 KWG
# create 5 new sub-tasks in SWG project for the same # SWG-101 using stdin to get new sub-tasks' summaries from # the user $ jcr st CARD-101 -n 5 <<EOF This is a summary for the first sub-task. This is a summary for the second sub-task. This one is folded using leading whitespace on lines with continuation of the text. Third sub-task. {{{Fourth sub-task's summary.}}} Fifth sub-task. EOF
# create as many sub-tasks in VIRT project for CARD-102 as # provided summaries using stdin $ jcr st CARD-101 VIRT -n EOF <<EOF First issue's summary... Second issue's summary.. Third issue's summary... ... EOF
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF jcr,create,creat,crea,cre,cr,c sub-task,sub,st,s k,e,n plumbing:issues create -T Sub-Task -L Implements \ -F Summary,assignee=$me $keys $args EOF
2.1.13. Create a new Blueprint
$ jcr blueprint [<parent_issue_keys>] [-k] [-e] [-n <number>]
Create a new sub-task.
Examples:
# create a new blueprint for CARD-100 using an editor to get # field values from the user $ jcr blueprint CARD-100 -e
# create a new blueprint for CARD-100 using stdin to get # summary from the user $ jcr bp CARD-100 <<EOF Summary: This is a new summary Description: {{{ This is a multiline description for the blueprint. .... }}} Depends on: CARD-120 Labels: SOME_LABEL EOF
# create 5 new blueprints for the same CARD-101 using stdin # to get new blueprint's field values from the user $ jcr bp CARD-101 -n 5 <<EOF Issue: EOF
# create as many blueprints for CARD-102 as provided # summaries using stdin $ jcr bp CARD-101 -n EOF <<EOF First blueprint's summary... Second blueprint's summary.. Third blueprint's summary... ... EOF
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF jcr,create,creat,crea,cre,cr,c blueprint,blue,blu,bl,bp,b k,e,n plumbing:issues create -T Blueprint -L Implements -F \ Summary,Description,assignee=$me $keys $args EOF
2.1.14. Edit an issue
$ jed [-k] [-e] [<issue_keys...>]
Edit a JIRA issue.
Examples:
# edit an issue using an editor $ jed PMWG-100 -e
# edit an issue by setting its listed fields $ echo 'This is a new summary' | jed PMWG-100 -F Summary
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF jed,edit,edi,ed,e blueprint,blue,blu,bl,bp,b k,e plumbing:issues edit $keys $args EOF
2.1.15. Start working on an issue
$ jtr start [-k] [-e] [-m <msg>] [<issue_keys...>]
Transition a JIRA issue into the `In Progress` status.
Examples:
# Start working on an issue $ jtr start PMWG-100
# Start working on a couple of issues and add a comment $ jtr PMWG-100,PMWG-101 -c <<EOF This is a comment to be added to both issues after their statuses are changed to `In Progress`. EOF
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF jtr,transition,transitio,transiti,transit,transi,trans,tran,tra,tr,t k,e,m plumbing:issues transition $keys 'In Progress' $args EOF
2.1.16. Resolve an issue
$ jtr resolve [-k] [-e] -m <msg>] [<issue_keys...>] <resolution>
Transition a JIRA issue into the `Resolved` status and set its resolution to the one provided.
Examples:
# Resolve an issue as Delivered also adding a comment to it $ echo 'Finally!' | jtr resolve PMWG-100 Delivered -c
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF jtr,transition,transitio,transiti,transit,transi,trans,tran,tra,tr,t\ resolve,resolv,resol,reso,res,re,r plumbing:issues transition $keys $args k,e,m EOF
2.1.17. Log time spent on an issue
$ jwt [-k] [<issue_keys...>] <from_date> <effort>
Add work log entry for the issue specified reporting <effort> hours spent starting from <from_date>.
Examples:
# Log time spent on an issue during this week (on Friday) $ jwt KWG-100 -5d 3.5h
# Log time spent on a few issues during the week $ jwt -k <<EOF # issue key to report time against KWG-100 # date when the reported chunk of work was started -5d # Amount of time spent 2h KWG-101 -3d 50m KWG-102 -1d 1d EOF
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF jcr,create,creat,crea,cre,cr,c blueprint,blue,blu,bl,bp,b plumbing:worklog add $keys $args
EOF
2.1.18. Link dependencies
$ jln depends [<issues_to_link...>] [<issues_to_link_to...>]
Link <issues_to_link...> as depending on <issues_to_link_to...>
Examples:
# Link PMWG-101 as depending on PMWG-100 $ jln depends PMWG-101 PMWG-100
# Link PMWG-101,PMWG-102 and PMWG-103 as depending on # PMWG-100 $ jln dep PMWG-101,PMWG-102,PMWG-103 PMWG-100
# Links PMWG-105 as depending on PMWG-101 and PMWG-102 $ jln d PMWG-105 PMWG-101,PMWG102
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF jcr,create,creat,crea,cre,cr,c blueprint,blue,blu,bl,bp,b plumbing:issues link -L Implements $keys $args k,e,n EOF
2.1.19. Link implementors
$ jln implements [<issues_to_link...>] [<issue_to_link_to>]
Link <issues_to_link...> as depending on <issue_to_link_to>
Examples:
# Link PMWG-101 as implementing PMWG-100 $ jln implements PMWG-101 PMWG-100
# Link PMWG-101,PMWG-102 and PMWG-103 as implementing # PMWG-100 $ jln impl PMWG-101,PMWG-102,PMWG-103 PMWG-100
# Links PMWG-105 as depending on PMWG-101 and PMWG-102 $ jln d PMWG-105 PMWG-101,PMWG102
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF jcr,create,creat,crea,cre,cr,c blueprint,blue,blu,bl,bp,b issues link -L Implements $keys $args k,e,n EOF
2.1.20. Unlink dependencies
$ jul depends [<issues_to_unlink...>] [<issues_to_unlink_from...>]
Unlink <issues_to_unlink...> as depending on <issues_to_unlink_from...>
Examples:
# Unlink PMWG-101 as depending on PMWG-100 $ jul depends PMWG-101 PMWG-100
# Unlink PMWG-101,PMWG-102 and PMWG-103 as depending on # PMWG-100 $ jul dep PMWG-101,PMWG-102,PMWG-103 PMWG-100
# Unlink PMWG-105 as depending on PMWG-101 and PMWG-102 $ jul d PMWG-105 PMWG-101,PMWG102
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF jul,unlink,unlin,unli,unl,un,ul,u blueprint,blue,blu,bl,bp,b plumbing:issues unlink -L Implements $keys $args k,e,n EOF
2.1.21. Unlink implementors
$ jul implements [<issues_to_unlink...>] [<issue_to_unlink_from>]
Unlink <issues_to_unlink...> as depending on <issue_to_unlink_from>
Examples:
# Link PMWG-101 as implementing PMWG-100 $ jln implements PMWG-101 PMWG-100
# Link PMWG-101,PMWG-102 and PMWG-103 as implementing # PMWG-100 $ jln impl PMWG-101,PMWG-102,PMWG-103 PMWG-100
# Links PMWG-105 as depending on PMWG-101 and PMWG-102 $ jln d PMWG-105 PMWG-101,PMWG102
This command is defined using the following plumbing command:
$ jic --plumbing command add <<EOF jul,unlink,unlin,unli,unl,un,ul,u blueprint,blue,blu,bl,bp,b issues unlink -L Implements $keys $args k,e,n EOF
-------- 8< -------- 8< -------- 8< -------- 8< --------
Thank you for reading through down to this place. It is important for everyone involved to get jic capable of doing the most needed things first.
Please, send me your feedback (whatever it is, including "looks sane" kind of it). :)
-
Serge Broslavsky