Assisted Workflow: a CLI tool to speed up simple git workflows
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".
Our workflow steps are:
- Start a pivotal/github/JIRA story, creating a new git branch for the new feature/bug fix
- Commit the changes, pushing to a new remote branch
- Submit a pull-request, allowing another team member to review the code, and merge into master if everything is ok
- Finish the story, removing both local and remote feature branches
- 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
aw - the CLI tool
- $ 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
- $ 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
- $ 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.
assisted_workflow is provided as a ruby gem. Install it with:
$ gem install assisted_workflow
.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.
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
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
$ 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
releasebranch 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!