Having a defined workflow has huge advantages. It adds discipline and structure to a process, helps focus on one task at the time, and a whole lot more. Here at Doximity, the mobile team has honed one of its workflows by applying a general convention for branching and pull requests on Github. This convention is great because it leads to structured and manageable repositories. But, as you’ll see below, it can be a bit labor intensive.

Let’s start with a look at a branch graph of a repository. It usually looks like this in its most basic form:

In this process, the changes for each feature are code reviewed on their own pull request to the version branch. And each merge to the Master marks a new release.

It looks simple, but just imagine what you need to do in order to create a pull request for a simple one-line fix on the code.

$ git checkout -b new_branch_name
$ git add -A
$ git commit -m "commit message"
$ git push --set-upstream origin new_branch_name

After all that, you’d open up github.com and create a pull request from the site. At Doximity, we also link the created pull request with its corresponding story on Pivotal Tracker by putting the story link in the PR, and vice versa.

To me this is way too much work for committing a single line change. It’s also really redundant for major changes. Thankfully, there’s a tool to help.

Introducing PRH (Pull Request Helper)

Pull Request Helper (prh) is a simple python command line interface (CLI) application. It uses subprocess in python and an API from hub to do all that work above with a simple and easy command. The equivalent of the above process with prh is:

$ prh -b new_branch_name

That’s all there is to it! In the process, prh:

  • created a new branch called new_branch_name
  • committed all the changes (with the default commit message)
  • pushed the commits to origin
  • created a pull request using hub API (with the title of "new branch name")
  • opened the pull request in a browser

But wait. What about linking the story to the PR? For that, all you need to do is use -m option and add a link to your story, like this:

$ prh -b new_branch_name -m https://your/pivotaltracker/story/link

You can see the results on Pivotal Tracker as a comment on the story:

You can also see it on your PR as the pull request body:

The case above is only one of many supported by prh. You can also use it to create a PR when you’re already in a feature branch (using -upto option) or even commit your code in a new branch and create its PR to another branch (using both -b and -upto together).

There are many more options for customization. These include -pb for adding a message to the pull request body and -pt for changing the default pull request title. Or, if you wish to add just one of the changed files, you can use -a option with the file’s path.

No matter how you customize, automating the committing process using prh will save time and prevent mistakes.

To read about all the customization options and download prh visit PullRequestHelper.

Looking Forward

We wrote prh with extensibility in mind. That means it won’t take much for you to fork the repository and make it match your existing workflow with some simple modifications.

Pull Request Helper is an open source project. You can contribute by adding and improving the code, requesting features, or reporting bugs. And don’t forget to check out the requested features at the issues page of the project. Thanks and enjoy prh!


python 2.7

Get started using PRH