Fotingo (beta)

A CLI to ease the interaction between Git, GitHub and Jira when working on tasks.

Installation

Run:

yarn global add fotingo@next

Or if yu prefer npm:

npm install -g fotingo@next

Requirements

The first time that you run fotingo, it will ask you for some information:

A GitHub personal access token. You can create one here. Only repo permissions are needed
Your Jira username
Your Jira server root URL
A Jira access token for your user. You can create one here

Usage

The command line supports three main commands: start, review and release.

start

fotingo start <issue-id> - Start working on a new issue.

Assign the issue to current user
Clean current working directory (stash it)
Checkout latest master
Create a new branch that follows a naming convention
Set the issue to In Progress

If you want to set an issue in progress in Jira without creating a new branch, you can use the -n (--no-branch-issue) option.

If you want to create a new issue you can use the -c (--create) option. You will also have to specify the type (-t or --type) and project (-p or --project) where the issue is going to be created. Optionally you can also specify labels (-l or --label) and a description for the created issue (-d or --description).

The next command creates a bug in the Test project with the label team-test:

fotingo start -t But -p Test -l team-test -d "This is the description" -c "This is the title"

review

fotingo review -l mylabel -l "Another Label" -r github_user - Submit a pull request for review.

Halt if you are not in the correct branch or if the pull request already exists
Push the current branch to GitHub
Create a new pull request against master with the commit messages and a link to the issue. Default editor will open so user can edit message
Add labels and review requests, if any, to the pull request
Set issue to In Review and add comment with a link to the pull request

Labels and reviews lookup is done using fuzzy search, meaning that if you want to add the Needs tests label to a PR you can just use -l "tests" and the correct label will be applied or you will be prompted to select the correct if multiple options match the search.

If you just want to create a pull request without connecting to Jira at all, you can use the option -s (--simple).

release

fotingo release -i <issue-id> -i <another-issue-id> <release-name> - Creates a Github and Jira release

Create a Jira version with the indicated name (e.g. 1.0.5)
Set the issues fix version to the newly created version
Update the issues' status to Done
Create a GitHub release pointing to the Jira release. Default editor will open so user can edit the release notes

If you just want to create a release in Github without connecting to Jira at all, you can use the -s (--simple) option.

Using the defaults

By default fotingo will ask the user to edit the contents of pull requests and releases as well as to select the correct reviewer / label when there are multiple matches for the search. Using the -y (--yes) option you can skip these questions and tell fotingo to use the defaults / first matches.

A different base branch

The default base branch for any fotingo command is master, but sometimes this is not true for some people. In that case, the option -b (--branch) allows to specify the base branch in every command. This config can also be made permanent via the configuration file. The branch lookup is also done via a fuzzy search like it is done for labels and reviewers

Configuration

Fotingo will try to guess most of the information based on the user environment, but there is some data that it still needs to be stored. On the first run, fotingo will create a .fotingorc configuration file inside your home directory. This file is used to store access tokens and some basic configuration information.

Local configuration files

You can create project-specific configuration files. Just create a .fotingorc file inside your project root folder. This file, needs to be in JSON format as well. You can also overwrite global configuration in this file. An example config file may just be:

{
  "github": {
    "baseBranch": "develop"
  }
}

Configuration properties

Fotingo will use as many defaults as possible to make it easier to use, but maybe you want to change some of the defaults. In that case, you can update any of the next properties in a fotingo configuration file

Path	Description	default
git.remote	Git remote to use	origin
git.baseBranch	Git base branch to use when creating new branches	master
git.branchTemplate	Template used when creating a new branch	See templates
github.authToken	Auth token to connect to Github	-
github.baseBranch	Base branch to use to create PRs	master
github.owner	Owner of the repository when creating a PR	Extracted from remote
github.repo	Name of the repository when creating a PR	Extracted from remote
github.pullRequestTemplate	Template to use when creating a PR	See templates
jira.user.login	User login to connect to Jira	-
jira.user.token	User token to connect to Jira	-
jira.releaseTemplate	Template to use when creating a release	See templates
jira.root	URL root to the Jira server	-

Templates

There are some configuration properties in fotingo that are template based, meaning that they can be customized to better suit your needs.

You can use { and } to interpolate the desired data. This is the data that is available in each template:

jira.releaseTemplate
- version. The version name specified through the CLI
- fixedIssuesByCategory. Text that contains a list of the fixed issues by category
- fotingo.banner. Banner that indicates that the release was created with fotingo
github.pullRequestTemplate
- branchName. Name of the branch
- changes. List of the commit messages in the PR
- fixedIssues. Text with the comma separated list of the fixed issues
- firstIssue.summary. Summary of the first Jira issue in the PR
- firstIssue.description. Description of the first Jira issue in the PR
- fotingo.banner. Banner that indicates that the release was created with fotingo
git.branchTemplate
- issue.shortName. A short name that represents a Jira issue type (e.g. f for features).
- issue.key. The key of the issue.
- issue.sanitizedSummary. This is the summary of the issue, sanitized for use as a branch name.

Why fotingo?

When working on Jira backed projects, I see a common pattern I repeat several times a day:

Pick an issue in Jira to work on
Assign the issue to me and transition it to in progress
Create a new branch in my local Git repository that follows certain naming conventions
Do the work and commit some changes
Create a GitHub pull request with a description very similar to the ticket and a link back to the Jira issue
Set different GitHub labels and request reviewers
Set the Jira issue state to In Review and add a comment with the pull request URL
Merge the PR and deploy the code via a CI server
Create a Jira release and update the issue fix version and status
Create a GitHub release that points back to Jira and has meaningful release notes

This seems like a reasonable workflow, but when addressing several issues on a given day, this process becomes very cumbersome. Thus... Fotingo.

Debugging

If you run into problems, you can get more verbose output from the tool by adding:

DEBUG="fotingo:*" fotingo ...

Running locally

In order to run the tool locally you will have to clone the repo and then run:

yarn link

After that, just run yarn run watch and the script will compile with every change you make to the source code.

Troubleshooting

`fotingo not found` when installing with yarn.

You need to have the directory where yarn installs global packages in your path. You can read more about that here and here. You just need to add export PATH="$(yarn global bin | grep -o '/.*'):$PATH" to your .bash_profile or equivalent.

Contributing

If you want to extend this tool with anything, feel free to submit a pull request.

What is a fotingo?

This word in Spanish (Canary Islands) means Rickety old car, but what is more interesting is the word's origin: In 1908 the Ford Motor Company released the Ford Model T with the slogan of foot 'n go, as in, just put your "foot on the pedal and go". In some hispanic regions this morphed into the current version of fotingo. With a single command, you can put your foot 'n go on your next issue.

mack1070101/fotingo