A CLI to ease the interaction between Git, GitHub and Jira when working on tasks.
Run:
npm install -g fotingo
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
$ npm install -g fotingo
$ fotingo COMMAND
running command...
$ fotingo (-v|--version|version)
fotingo/4.4.0 linux-x64 node-v16.18.1
$ fotingo --help [COMMAND]
USAGE
$ fotingo COMMAND
...
fotingo help [COMMAND]
fotingo inspect
fotingo open [SOURCE]
fotingo release RELEASE
fotingo review
fotingo start [ISSUE]
fotingo verify
display help for fotingo
USAGE
$ fotingo help [COMMAND]
ARGUMENTS
COMMAND command to show help for
OPTIONS
--all see all commands in CLI
See code: @oclif/plugin-help
Output information about the specified element. If no element is specified, output information about the execution context
USAGE
$ fotingo inspect
OPTIONS
-b, --branch=branch Name of the base branch of the pull request
-i, --issue=issue Specify more issues to include in the release
See code: src/commands/inspect.ts
Open the pull request or the jira ticket from the fotingo context in a browser
USAGE
$ fotingo open [SOURCE]
ARGUMENTS
SOURCE (jira|pr) [default: jira] Source place that you want to open
See code: src/commands/open.ts
Create a release with your changes
USAGE
$ fotingo release RELEASE
ARGUMENTS
RELEASE Name of the release to be created
OPTIONS
-i, --issues=issues Specify more issues to include in the release
-n, --noVcsRelease Do not create a release in the remote VCS
-s, --simple Do not use any issue tracker
-y, --yes Do not prompt for any input but accept all the defaults
See code: src/commands/release.ts
Submit current issue for review
USAGE
$ fotingo review
OPTIONS
-b, --branch=branch Name of the base branch of the pull request
-d, --draft Create a draft pull request
-l, --labels=labels Labels to add to the pull request
-r, --reviewers=reviewers Request some people to review your pull request
-s, --simple Do not use any issue tracker
-y, --yes Do not prompt for any input but accept all the defaults
See code: src/commands/review.ts
Start working on an issue
USAGE
$ fotingo start [ISSUE]
ARGUMENTS
ISSUE Id of the issue to start working with
OPTIONS
-a, --parent=parent Parent of the issue to be created
-b, --branch=branch Name of the base branch of the pull request
-d, --description=description Description of the issue to be created
-k, --kind=kind Kind of issue to be created
-l, --labels=labels Labels to add to the issue
-n, --no-branch-issue Do not create a branch with the issue name
-p, --project=project Name of the project where to create the issue
-t, --title=title Title of issue to create
See code: src/commands/start.ts
Verify that fotingo can authenticate with the remote services
USAGE
$ fotingo verify
See code: src/commands/verify.ts
Fotingo can be used as a semantic-release plugin via https://github.com/tagoro9/semantic-release-fotingo
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.baseBranch | Git base branch to use when creating new branches | master |
git.branchTemplate | Template used when creating a new branch | See templates |
git.remote | Git remote to use | origin |
github.authToken | Auth token to connect to Github | - |
github.owner | Owner of the repository when creating a PR | Extracted from remote |
github.pullRequestTemplate | Template to use when creating a PR | See templates |
github.repo | Name of the repository when creating a PR | Extracted from remote |
jira.releaseTemplate | Template to use when creating a release | See templates |
jira.root | URL root to the Jira server | - |
jira.status | Regexes to identify workflow statuses | See jira status |
jira.user.login | User login to connect to Jira | - |
jira.user.token | User token to connect to Jira | - |
Some of the fotingo configuration properties can be set using environment variables.
Variable | Property |
---|---|
FOTINGO_JIRA_ROOT | jira.root |
FOTINGO_JIRA_USER_LOGIN | jira.user.login |
FOTINGO_JIRA_USER_TOKEN | jira.user.token |
FOTINGO_GIT_REMOTE | git.remote |
GITHUB_TOKEN | github.authToken |
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
. fotingo will give preference to the template specified in.github/PULL_REQUEST_TEMPLATE/fotingo.md
,PULL_REQUEST_TEMPLATE.md
,.github/PULL_REQUEST_TEMPLATE.md
file. If those files don't exist, it will use the template specified in the configuration file.branchName
. Name of the branchchanges
. List of the commit messages in the PRfixedIssues
. Text with the comma separated list of the fixed issuessummary
. Pull request summary. Summary of the first Jira issue in the PR or first commit header if there are no fixed issuesdescription
. Description of the first Jira issue in the PR or first commit body if there are no fixed issuesfotingo.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.
Fotingo internally uses 5 status for an issue: Backlog
, Selected for Development
, In progress
, In review
, Done
.
It automatically tries to map these statuses to Jira statuses, but sometimes projects may have simplified statuses in
Jira and fotingo won't be able to do the mapping automatically. If that is the case, the jira.status
config can be
used to help fotingo do the mapping. Each entry should be a regex to map to that status:
{
"jira": {
"status": {
"BACKLOG": "backlog",
"IN_PROGRESS": "in progress",
"IN_REVIEW": "review",
"DONE": "done",
"SELECTED_FOR_DEVELOPMENT": "(todo)|(to do)|(selected for development)"
}
}
}
Multiple fotingo status can point to the same Jira status.
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.