Evan Oxfeld

5 Ways to Improve Pull Requests to Private Projects

At VBrick we’ve hosted our private projects on GitHub Enterprise for the last few months. Pull requests are the team’s code review step so only blessed changes end up merged into our mainline branch. Even though team members have mixed levels of git and GitHub experience, the current process is as lightweight as it gets – any developer on the project can submit or merge a pull request.

The following are some best practices I’ve learned from my experience using GitHub for private as well as open source projects. Many open source lessons carry over – if you think about it, submitting a pull request to Twitter Bootstrap to add semicolons to their JavaScript[1] and submitting sweeping coding style changes to your team’s project are both wastes of time.

I assume the reader has basic working knowledge of git, GitHub, and what makes for a good commit / commit message.

Actually use pull requests

Pull requests encourage critical discussion around code changes, improve code quality, and increase team knowledge of the codebase. When pull requests are merged, team members and project watchers are notified that the repository was updated with blessed changes. What’s not to like?

Make your pull requests small and easy to review

As the contributer of a pull request, you’re the expert on your changes. Therefore to spread knowledge and receive meaningful feedback you should strive to make life as easy as possible for reviewers.

Use a concise title. If you don’t use GitHub issues, link to the issue in your project’s issue tracker. Summarize what has changed and why the changes are necessary, particularly if the pull request is large or if the issue’s implementation is not obvious.

When possible, don’t submit a massive pull request. Submit separate pull requests for each logical set of changes. Within the pull request, strive for commits that are atomic – that is, the commit represents a single refactoring or distinct change to the system.

Collaborate before the pull request

Whether in person or remote, discuss the design of a feature implementation or bug fix prior to submitting a pull request. If you’re like me and find pair programming effective, work as a pair before submitting the pull request.

Keep the process lightweight

The freedom that any developer on my project can merge any of the project’s pull requests at times resembles anarchy. That said, assigning reviewers to pull requests would create a bottleneck for my team. On a private project, the contributor of a pull request is the expert on the changes and the person with the most skin in the game to ensure the pull request is reviewed and merged in a timely fashion.

As a developer, if you don’t know who should review a pull request, ask.

Use forks

Resist the temptation to work on separate branches in a shared repository. As a developer, it’s easier to experiment when forks are treated as sandboxes and branches in forks considered public history is the exception rather than the rule.

1. bootstrap-dropdown.js clearMenus() needs ; at the end

Should Node-Unzip Have a Future?

Cross posted from https://github.com/EvanOxfeld/node-unzip/issues/50

I continue to be floored by the response to node-unzip. While the original implementation was written on a lark, I carried on as a means to better understand streams, arguably the killer feature of NodeJS. Since that time, I’ve changed companies, ceased personally using this library, and experienced a number of major life events, particularly becoming a father.

I also learned that the zip format is problematic and cannot be perfectly streamed – see this Apache doc. That said, if despite the major hangups as well as quality non-streaming NodeJS modules, such as decompress, there’s continued interest in this project, I’ll work to take the project to a stable 1.0.0, merge outstanding pull requests, and most importantly, seek collaborators who use this library in production.

Thank you and let me know your thoughts on the project on GitHub.

Sneakernet Solved With Git Bundle

Recently I wanted to transfer a presentation from one machine to another, and unfortunately I was unable to connect to the Internet. Similar to life when it was entirely offline or whenever Github is vexingly down, I was in a classic sneakernet scenario. If you haven’t heard the term, sneakernet is slang for walking media such as a disk or USB flash drive from one machine to another in order to transfer files. Bonus points if you bring a pedometer along.

Ordinarily I’d copy the presentation onto a USB stick, transfer the presentation to the second computer, and be done. In a feeble attempt at version control, maybe I would have renamed the file “Presentation DRAFT1 FINAL”. However, this time my presentation was in HTML/JavaScript and already version controlled with Git. While I could use git to create and apply patches across to the unconnected machine, there’s an easier way - git bundle.

Create the Git Bundle

Think of git bundle as zipping or tarring up your repository with benefits - namely that you can transfer the exact git objects that store your commits, branches, and tags. A git bundle mimics a remote, enabling fetching, pulling, and diffing between machines that aren’t otherwise connected.

To create a bundle named “repo.bundle” containing each and every commit in the master branch:

git bundle create repo.bundle master

Especially if you anticipate transferring more commits in the future, tag the current commit on master.

Clone the Bundle on the Second Machine

If the repository does not already exist on the second machine, it’s easiest to clone directly from the bundle.

To clone into the directory “myRepo” and check out the branch master:

git clone repo.bundle myRepo -b master

Verify the master branch. My preferred method is viewing a graph of the commits:

git log --oneline --decorate --graph

Transferring Additional Commits

We could once again bundle the entirety of the master branch and do a git clone on the second machine, but we’d sacrifice any additional work on that box. Instead, bundle master starting from the previous bundle’s most recent commit:

git bundle create more.bundle lastBundleTag..master

On the second machine, verify the bundle then pull the contents into master:

git bundle verify more.bundle
git pull more.bundle master

Once again, verify the master branch and the recently transferred commits:

git log --oneline --decorate --graph


Using git bundle makes version controlling repositories across unconnected machines simple. Additionally, all the elements of the git workflow remain at your beck and call. For example, consider creating a long running branch for changes that are only applicable to the second machine for reasons such as easy diffing between machines.