Jetkcli

Jira Embedded Terminal Kung fu Command-line interface

⚠️ Jetkcli is still a work in progress ⚠️

Please don't rush into installing and using jet before you understand why and how to use it. Take time to read this section, this might save you some precious time.

Shall I use Jet ?

Jet is intended to work on a very specific context :

• You are working with git and want to enforce naming conventions for branches and commits.
• You are working with Jira, and wants to get some repeating/boring tasks automated.

If your project doesn't match this description you probably don't want to use Jet (and won't be able to anyway).

What Jet can do for me ?

1. When working on a project developers often try to enforce good practices regarding commit messages, branching model Jira workflow etc. Unfortunately people, come and go, humans do mistakes and things get messy.

2. When working with Jira we do a lot of repeating tasks that conceptually matches actions made with git. Let us assume the following scenario :

Alice the lead dev asks Bob to implement a new command in the jet project. She tells Bob to take the corresponding issue. Bob start working on JET-1 and assign it to himself transitioning the issue state to "Work in progress". He checks out a new local git branch with the name feat/JET-1. When he is done editing the code Bob creates a commit with the following message : feat(command): add jet 1 feature [JET-1]. Bob is done coding so he pushes is work to the remote repository and submit a PR. He assign Alice to review it. He change the issue state on jira to "Review" and assign it to Alice.

Jet's goal is to reduce this kind of repetition and automate some tasks by unifying related jira and git workflow when possible.

Here are the planned feature to achieve this goal :

• It enforce a branching model and a commit message convention referencing your issues (see conventional commit) ✔️
• Handy commit generation command matching your convention model (all you need to type is the commit message) ✔️
• Automatic branch naming ✔️
• Transition issue state and assignment automatically when you start working on one ✔ ️
• Submit PRs on the git platform where your project is hosted.
• Automatically submit your PRs on your git platform (bitbucket, github, gitlab) and assign reviewers to it.
• Transition issue state and assignment automatically when you submit a PR.
• Read issue description and comments from the command line ✔️
• Generate markdown changelogs

Installation

To install Jetkcli you will need rust installed on your system.

you can then run cargo install jetkcli

Global settings

Before using jet you will need to create the following config file :

Platform	Value	Location
Linux	$XDG_CONFIG_HOME or $HOME/.config	/home/alice/.config/jet/config.toml
macOS	$HOME/Library/Preferences	/Users/Alice/Library/Preferences/jet/config.toml
Windows	{FOLDERID_RoamingAppData}	C:\Users\Alice\AppData\Roaming\jet\config.toml

You can copy the example from doc/example.config.toml

# "my_corporate_jira" is an arbitrary value, put whatever you want here
[servers.my_corporate_jira]

url = "corporate.jira.com"
username = "bob.smith@yopmail.com"
password = "hunter2"

[servers.local]

url = "http://localhost:8080"
username = "bob.smith"
password = "hunter2"

Private project settings

TODO

Shared project settings

This file is generated in ${project_dir}/.jetp/config.shared.toml. The example above show the default generated file.

[jira]
# project short name in jira, generated from `jet init` -p arg
project_name = "MYP"
# infered for global settings with one server or from `jet init` -s arg
server_name = "local"
server_url = "http://localhost:8080"

# Default values, change this if you have custom issue types
[jira.workflow]
wip = "In Progress"
done = "Done"
todo = "To Do"

[git]
# Default conventional commit prefix
commit_types = ["fix", "feat", "chore", "style", "doc"]
# Default branch prefix
branch_types = ["fix", "feat", "chore", "style", "doc"]
# Default branch separator (ex: feat/JET-1)
branch_separator = "/"

Commands

Init

The init command does the following :

• check that current dir is a git repository.
• check that your Jira project exist in the remote jira server.
• create .jet directory and default local configurations.

jet init -p PRO -s my_jira_server

If you have only one Jira server configured in $XDG_CONFIG_HOME/jet/config.toml you can omit the --server flag.

Checkout

Like git checkout the jet checkout allow you to change the working branch and create new ones with the -b flag. When checking out a new branch jet requires a branch prefix followed by an issue key

This does the following :

• Assign the issue to the user defined in $XDG_CONFIG_HOME/jet/config.toml.
• Transition the issue to the state wip set in .jet/config.shared.toml
• Create and checkout a new local branch with the following name {prefix}{separator}{issue_key} see(shared settings)

jet checkout -b feat JET-1  # create and checkout a branch named "feat/JET-1"

When you checkout an existing branch :

• Warn if the current user is not assigned to the issue
• perform git checkout

jet checkout feat JET-1

If there is exactly one branch for this issue you can use the short version :

jet checkout JET-1

Commit

Jet generate sub-commands matching your configured commit prefix (see project settings shared:

jet feat "this is a cool feature"

Assuming you are working on the issue JET-1 this will produce the following commit feat: this is a cool feature [JET-1]

Additionally you can provide a scope for your commit :

jet fix "toml parse error" config

This will produce the following commit fix(config): toml parse error [JET-1]

Submit

TODO