A CLI to ease the interaction between Git, GitHub and Jira when working on tasks.
Run:
yarn global add fotingo@next
Or if yu prefer npm:
npm install -g fotingo@next
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
The command line supports three main commands: start
, review
and release
.
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"
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
).
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.
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.
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
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.
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"
}
}
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 | - |
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 CLIfixedIssuesByCategory
. Text that contains a list of the fixed issues by categoryfotingo.banner
. Banner that indicates that the release was created with fotingo
-
github.pullRequestTemplate
branchName
. Name of the branchchanges
. List of the commit messages in the PRfixedIssues
. Text with the comma separated list of the fixed issuesfirstIssue.summary
. Summary of the first Jira issue in the PRfirstIssue.description
. Description of the first Jira issue in the PRfotingo.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.
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.
If you run into problems, you can get more verbose output from the tool by adding:
DEBUG="fotingo:*" fotingo ...
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.
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.
If you want to extend this tool with anything, feel free to submit a pull request.
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.