Things I Wish I Had Known | Pull Requests
Last week was the first time that I had the opportunity to work with production-level code, and I am happy to say that my first-ever pull request (PR) was accepted! It was such a wonderful feeling, and I must admit that I was overly excited. However, it did take me several hours to figure out how to work with a repository maintained by other developers. So, here are a few of the key things that I learned in dealing with PRs.
Branching Out
The first thing to master with PRs and version control with remote repositories is branching. I learned this lesson the hard way when I tried to push all of my feature changes to the master branch. Not such a good idea! So, let’s check out the commands for creating and maintaining a new branch.
Create Branch
When creating a branch, the best practice is to name it after the issue that you are attempting to solve. For instance, if you are fixing the navigation bar, and the related Github issue is #378, you want your branch to read something like this: ms-nav_bar_378. Here, the “ms” stands for my initials: Michael Schiumo. This ensures that it is easy to determine who is responsible for which branches.
To create a new branch locally, run:
Now, push to the remote origin branch using:
To check that it is connected properly, you can make a simple initial commit:
Great! Now, you have two new branches — one local, and one remote. This is where you should commit all code that concerns the feature on which you are working.
Making the PR from Github
First, find the feature branch that you created on Github. Once you have added changes to the feature branch, and you’re ready to submit for review, you can make a Pull Request from that branch.
One quick lesson: it is good to hit the “Compare” option to see how many commits and how many files were changed. I made the mistake of uploading a massive binary file that was completely unnecessary, because I didn’t check the changes that had been made before submitting the PR. In a world in which optimization is key, this is a big mistake to make.
Description
Add a quick, one-line description (headline) of the changes that you made to the feature branch. For example — “realigns the ‘Home’ button with the remainder of the Nav bar.” Short, simple, and easy to read.
In the text box below the headline, make a reference to the issue number, like so — “resolves issue #378.” This will make sure that Github closes the issue once the branch is merged.
If relevant, especially for UI changes, include a snapshot of what the change may look like. It is sometimes helpful to highlight certain pieces of the UI in the snapshot that were altered, particularly for the person who is reviewing the code.
The next step is to pray that your code is useable!
Fuel my coffee habit, please! I promise I’ll produce more content with a few shots of espresso coursing through my veins.
Clean Up
Now, your PR has been accepted, and merged. Hooray! You’ve made a contribution! Once the PR has been accepted and merged, the feature branch will be deleted remotely.
With that said, it is easy to pile up tons of feature branches on your local repository, so make sure to get rid of them once they are obsolete.
Run:
That should take care of the local branch.
Things to Keep in Mind
One of my biggest issues was trying to get rid of commits that I didn’t want to push to the remote feature branch. So, the easiest way is to do the following:
So, this will return the file that you specify to its original state (before you made changes to it).
Rebase vs. Merge
If you have a lot of commits, and there are too many moving parts, you can always rely on a rebase or a merge. That’s a topic for another time, but I will leave a link here to a resource that explains how to use each method.
Sum It Up
Now, you are well on your way to making those bigger and bigger contributions to the codebase! The key takeaways are to make sure that you provide detailed descriptions, and check the commits that you have made before submitting the PR.
So, go impress the world with your newfound skills! Happy Coding!
