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.

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.

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:

1

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:

1

git clone repo.bundle myRepo -b master

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

1

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:

1

git bundle create more.bundle lastBundleTag..master

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

12

git bundle verify more.bundlegit pull more.bundle master

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

1

git log --oneline --decorate --graph

Conclusion

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.