A poet’s guide to submitting a pull request on GitHub

Last week I wanted to make a small change to the Site Scan ReCap client to improve the way Autodesk was processing our jobs. Rather than burden the cloud team with experimenting with settings and verifying results, distracting them from building delightful new features, I took it upon myself to do the monkeying. While modifying and testing the code was fairly straightforward thanks to some foolproof instructions from my amazing tech lead, I didn’t see anywhere on the web that clearly explained how to make a pull request from start to finish. What follows is that guide.

Step one: Create a branch locally

The basic idea of distributed development relies on multiple branches of the project being working on at the same time. In my case, my simple changes to the ReCap API client were being worked on at the same time as numerous other projects. To manage this distribution of labor, I need to create a branch of the project on which I, and I alone, will work.

To do this, run

git checkout -b “branch_name”

from the terminal. -b specifies that you want to create a new branch, which you do here. You can do this before or after you have made your changes. This is just creating a branch on your local machine, which includes all of the changes you have made to the code.

2016-07-17 03.08.32 pm

Step two: verify branch locally

I can see that I was successful in creating this branch by running

git branch

2016-07-17 03.11.17 pm

You’ll notice that I see both my master and my new branch, with an asterisk next to my current branch.

Step 3: make edits

Edit your code! In my case, I wrote a very simple request client that returns Princess Leia’s attributes.

2016-07-17 03.17.22 pm

Step 4: Add locally

Next, you add the changes you just made to your local repository using

git add “file_name”

This terminal command does not return a response. If you’ve made changes to more than one file, you must add each file. You can check to see if your git add was successful, but typing

git status

which will return a list of the changed files.

2016-07-17 03.23.39 pm

Step 5: Commit locally

After you’ve add all of the files you’ve changed, the next step is committing them all to your local repository. Type

git commit -m “some message explaining the commit”

to do this. The -m bit is to very briefly explain to other contributors exactly what your changes will do.

2016-07-17 03.26.49 pm

Notice that if you run

git status

again, your changes disappear because they have already been committed.

Step 6: Push to repo

You’ve now added you changes to a local repository, but need to push them to your central store. Type

git push origin branch_name

2016-07-17 03.30.09 pm

Your branch is now up in the cloud and ready to be pulled into the main codebase.

Step 7: Make PR on github.com

Next, fire up your internet browser and navigate on over to github.com.

2016-07-17 03.34.55 pm

Inside my account, I see my hackathon project and I see that my test_branch is awaiting a pull request. Click compare and pull request and github will give the opportunity to write a more detailed description of the changes and see exact differences.

2016-07-17 03.36.22 pm

If everything is as expected, click pull request.

Step 8: Merge PR

Now your pull request is waiting for review. Generally, another member of your team will review the pull request and merge the code into master. Since I am the only one working here, I will employ the incredibly tacky tactic of merging my own PR.

2016-07-17 03.39.53 pm

Click merge pull request and your changes will be pushed into master. You will now have a little green square in your GitHub profile indicating you have contributed to this repo. Congratulations!

Step 9: Delete branch

The last step is just a little bit of housekeeping. It is typical to delete a branch after the PR is merged. To do this, navigate to the branches menu and click the icon next to your branch.

2016-07-17 03.44.14 pm

I hope this was helpful. If you are interested in developing on drones, be sure to check out my guide for using DroneKit Python and DroneKit Android as well.

One thought on “A poet’s guide to submitting a pull request on GitHub

  1. Pingback: Exploring the internet through REST APIs or how to build an HTTP client - Daniel D. McKinnonDaniel D. McKinnon

Comments are closed.