inaka

Latest blog entries

/
The Art of Writing a Blogpost

The Art of Writing a Blogpost

Mar 09 2017 : Matias Vera

/
SpellingCI: No more spelling mistakes in your markdown flies!

Feb 14 2017 : Felipe Ripoll

/
Fast reverse geocoding with offline-geocoder

Do you need a blazing fast reverse geocoder? Enter offline-geocoder!

Jan 18 2017 : Roberto Romero

/
Using Jayme to connect to the new MongooseIM REST services

MongooseIM has RESTful services!! Here I show how you can use them in an iOS application.

Dec 13 2016 : Sergio Abraham

/
20 Questions, or Maybe a Few More

20 Questions, or Maybe a Few More

Nov 16 2016 : Stephanie Goldner

/
The Power of Meeting People

Because conferences and meetups are not just about the technical stuff.

Nov 01 2016 : Pablo Villar

/
Finding the right partner for your app build

Sharing some light on how it is to partner with us.

Oct 27 2016 : Inaka

/
Just Play my Sound

How to easily play a sound in Android

Oct 25 2016 : Giaquinta Emiliano

/
Opening our Guidelines to the World

We're publishing our work guidelines for the world to see.

Oct 13 2016 : Brujo Benavides

/
Using NIFs: the easy way

Using niffy to simplify working with NIFs on Erlang

Oct 05 2016 : Hernan Rivas Acosta

/
Function Naming In Swift 3

How to write clear function signatures, yet expressive, while following Swift 3 API design guidelines.

Sep 16 2016 : Pablo Villar

/
Jenkins automated tests for Rails

How to automatically trigger rails tests with a Jenkins job

Sep 14 2016 : Demian Sciessere

/
Erlang REST Server Stack

A description of our usual stack for building REST servers in Erlang

Sep 06 2016 : Brujo Benavides

/
Replacing JSON when talking to Erlang

Using Erlang's External Term Format

Aug 17 2016 : Hernan Rivas Acosta

/
Gadget + Lewis = Android Lint CI

Integrating our Android linter with Github's pull requests

Aug 04 2016 : Fernando Ramirez and Euen Lopez

/
Passwordless login with phoenix

Introducing how to implement passwordless login with phoenix framework

Jul 27 2016 : Thiago Borges

/
Beam Olympics

Our newest game to test your Beam Skills

Jul 14 2016 : Brujo Benavides

/
Otec

Three Open Source Projects, one App

Jun 28 2016 : Andrés Gerace

/
CredoCI

Running credo checks for elixir code on your github pull requests

Jun 16 2016 : Alejandro Mataloni

/
Thoughts on rebar3

Thoughts on rebar3

Jun 08 2016 : Hernán Rivas Acosta

/
See all Inaka's blog posts >>

/
Assisted Workflow: a CLI tool to speed up simple git workflows

A photo of Flavio Granero wrote this on March 25, 2014 under clean, cli, github, inaka, tree .

A simple git workflow

After a couple of years and several projects delivered, here at Inaka we ended up developing a very simple git workflow that works with great efficiency for small agile teams.

Recently, there had been many articles showing git branch strategies, from some complex ones managed by git-flow tool, to simpler approaches where master is always ready to be deployed, and the work happens in branches created for each new feature/bug. We love the simple solutions, and we use something very similar to the model described by Juan Batiz-Benet and also by Scott Bacon on "Github Workflow".

Inaka Workflow

Our workflow steps are:

  1. Start a pivotal/github/JIRA story, creating a new git branch for the new feature/bug fix
  2. Commit the changes, pushing to a new remote branch
  3. Submit a pull-request, allowing another team member to review the code, and merge into master if everything is ok
  4. Finish the story, removing both local and remote feature branches
  5. Deploy master branch.

Although simple, we have a very long wiki page, describing all the git commands a developer may need to run, in every workflow step, for all kinds of projects. It is useful for new developers, and also to make sure everyone keeps a clean git history.

The differences found in our workflow are related to the tools and patterns we have introduced to make it even more convenient. When a developer creates a new pull request from an github issue, all the task info is moved and accessible to the reviewer, but when we are using another tool, like Pivotal Tracker or JIRA, this is not done automatically. That's why we've introduced a branch name pattern where the story info is always present. Every new feature/bug branch must be named with the user_name.story_id.story_description format (story_id is the task number in pivotal tracker, for instance) and every commit message or pull request title should include the respective story id as well.

The annoying repeatable actions

As you may realize, even a simple workflow like that involves repeatable actions for every step. The developer needs to know the git commands and the order to execute them (or read a help page showing that). Also, to integrate the steps with the external tools, extra actions are required in the browser: move a story to the new state (started, finished), copy the story id to generate the branch name, go to github to compare and create a new pull request.

After doing this several times for many projects, we realized a command line tool could prevent us from all the manual actions, and also make it easy to introduce new developers to the workflow. We called it assisted_workflow.

aw - the CLI tool

Assisted_workflow is a ruby gem that provides a command line tool (aw) with some useful commands to automate the workflow tasks. They main commands are:

  • $ aw start

List your next 5 pending stories in project tracker, showing a table with each story id, estimate and title. In order to include the already started stories in the list, run it with the -a flag.

  • $ aw start STORY_ID

Find and move the story to started state, creating a new git branch named with your username, story id and title. If the story is not estimated yet, you'll see an error message. You can set the estimate before starting it using the option -e 3, for instance.

  • $ aw submit

Submit the current story branch, creating a new github pull request. Once you're done with the story changes and everything is commited, run submit command to rebase the feature branch with master and submit it, creating a new pull request. The pull request url will be added as a note/comment in the story while moving it to finished state.

  • $ aw finish

Run finish command from a feature branch to check if the pull request has been merged into master, and to remove the local and remote branches safety.

There are shortcuts for these 3 main commands. You can also use $ aw s to start, $ aw u to submit and $ aw f to finish a story.

Installation

assisted_workflow is provided as a ruby gem. Install it with:

$ gem install assisted_workflow

Initial setup

assisted_worflow uses .awconfig files to store your credentials and settings. When running the setup command, it will create a global config file placed in your home folder, and one config file specific for a project, inside the project folder. In order to start using it, go to your project folder and run:

$ aw setup

You need to run this command for all projects where you want to use the tool. Make sure not to overwrite the global config file after you have stored settings there.

The setup command also generates a commit-msg git hook for the project. That hook is responsible for adding the story id for all commit messages made from a feature branch.

Setting up github

To use assisted_workflow with github issues, you just need to inform your access token. Even if you're using other story tracker, the github token is required to create pull requests. If you don't have a token yet, please follow the instructions to generate an oauth token.

Then, store the token with:

$ aw config github.token=MYGITHUBOAUTHTOKEN --global

Note we're using the --global flag, to store this info in the global config file, valid for all projects.

Setting up pivotal tracker

Pivotal tracker is supported also, and to setup it with aw you must copy the pivotal Api Token from your profile page and use aw config to store it:

$ aw config pivotal.fullname='YOUR PIVOTAL FULL NAME' --global
$ aw config pivotal.username='YOUR USERNNAME' --global
$ aw config pivotal.token=MYPIVOTALTOKEN --global

Those are the global settings, valid for all projects (if you don't want this, don't use --global flag). The username config will be used for feature branches names, as described above.

If you have those settings globally available, the only thing missing is the project_id, specific and stored in local .awconfig with:

$ aw config pivotal.project_id=00001

You may want to store the local .awconfig file into the project repository, preventing other users from running this configuration step.

Setting up jira

JIRA is another story tracker tool supported by aw. If your team is using the tool to organize the workflow, you can set this up storing your credentials in global config file:

$ aw config jira.username='YOUR JIRA USERNAME' --global
$ aw config jira.password='YOURJIRAPASSWORD' --global

Then in your project folder, store the project name and project uri:

$ aw config jira.uri='yourproject.atlassian.net'
$ aw config jira.project='APPLICATION'

Since JIRA is more customizable than the other tools, you need to inform the state names, when configuring the project details:

$ aw config jira.unstarted="YOUR UNSTARTED STATE NAME"
$ aw config jira.started="YOUR STARTED STATE NAME"
$ aw config jira.finished="YOUR FINISHED STATE NAME"

If you prefer, instead of using the command line, edit the .awconfig files in your project and home folders using a text editor, they are simple yaml files.

Coming up next

Some features are in our backlog for the next releases:

  • Support an "integration branch" config, to be used when the release branch is other than than master
  • Add an integrate setting, to include an extra step to be run before submitting a pull request. Useful to run the tests before submitting, for instance.
  • Figure out how to install the cli globally when using rvm.

We would love to know your thoughts about assisted_workflow! Feel free to open issues and send your pull requests to the github repository.

Stay tuned for new updates. We hope you enjoy this new way to manage your development workflow!

A photo of

Flavio Granero

Full Stack Developer